httpx

Documentation

Index

• Variables
• func BasicAuth(username, password string) string
• func DefaultShouldRetry(request *http.Request, response *http.Response, withDelay time.Duration) bool
• func DetectContentType(d []byte) (string, string)
• func Do(client *http.Client, request *http.Request, retries *RetryConfig, ...) (*http.Response, error)
• func NewRequest(method string, url string, body io.Reader, headers map[string]string) (*http.Request, error)
• func ParseNetworks(addrs ...string) ([]net.IP, []*net.IPNet, error)
• func ParseRetryAfter(value string) time.Duration
• func ReplaceEscapedNulls(data string, repl string) string
• func SetRequestor(requestor Requestor)
• type AccessConfig
  • func NewAccessConfig(resolveTimeout time.Duration, disallowedIPs []net.IP, ...) *AccessConfig
  • func (c *AccessConfig) Allow(request *http.Request) (bool, error)
• type Log
  • func NewLog(trace *Trace, trimURLTo, trimTracesTo int, redact stringsx.Redactor) *Log
• type LogWithoutTime
  • func NewLogWithoutTime(trace *Trace, trimURLTo, trimTracesTo int, redact stringsx.Redactor) *LogWithoutTime
• type MockRequestor
  • func NewMockRequestor(mocks map[string][]*MockResponse) *MockRequestor
  • func (r *MockRequestor) Clone() *MockRequestor
  • func (r *MockRequestor) Do(client *http.Client, request *http.Request) (*http.Response, error)
  • func (r *MockRequestor) HasUnused() bool
  • func (r *MockRequestor) MarshalJSON() ([]byte, error)
  • func (r *MockRequestor) Requests() []*http.Request
  • func (r *MockRequestor) SetIgnoreLocal(ignore bool)
  • func (r *MockRequestor) UnmarshalJSON(data []byte) error
• type MockResponse
  • func NewMockResponse(status int, headers map[string]string, body []byte) *MockResponse
  • func (m *MockResponse) Make(request *http.Request) *http.Response
  • func (m *MockResponse) MarshalJSON() ([]byte, error)
  • func (m *MockResponse) UnmarshalJSON(data []byte) error
• type Recorder
  • func NewRecorder(r *http.Request, w http.ResponseWriter, reconstruct bool) (*Recorder, error)
  • func (r *Recorder) End() error
• type Requestor
• type RetryConfig
  • func NewExponentialRetries(initialBackoff time.Duration, count int, jitter float64) *RetryConfig
  • func NewFixedRetries(backoffs ...time.Duration) *RetryConfig
  • func (r *RetryConfig) Backoff(n int) time.Duration
  • func (r *RetryConfig) MaxRetries() int
• type Trace
  • func DoTrace(client *http.Client, request *http.Request, retries *RetryConfig, ...) (*Trace, error)
  • func (t *Trace) SanitizedRequest(placeholder string) string
  • func (t *Trace) SanitizedResponse(placeholder string) string
  • func (t *Trace) String() string
• type WebSocket
  • func NewWebSocket(w http.ResponseWriter, r *http.Request, maxReadBytes int64, sendBuffer int) (WebSocket, error)

Variables

var ErrAccessConfig = errors.New("request not permitted by access config")

ErrAccessConfig is returned when provided access config prevents request

var ErrResponseSize = errors.New("response body exceeds size limit")

ErrResponseSize is returned when response size exceeds provided limit

var MockConnectionError = &MockResponse{Status: 0, Headers: nil, Body: []byte{}, BodyIsString: true, BodyRepeat: 0}

MockConnectionError mocks a connection error

Functions

func BasicAuth

func BasicAuth(username, password string) string

BasicAuth returns the Authorization header value for HTTP Basic auth

func DefaultShouldRetry

func DefaultShouldRetry(request *http.Request, response *http.Response, withDelay time.Duration) bool

DefaultShouldRetry is the default function for determining if a response should be retried

func DetectContentType

func DetectContentType(d []byte) (string, string)

DetectContentType is a replacement for http.DetectContentType which leans on the github.com/gabriel-vasile/mimetype library to support more types, and additionally returns the extension (including leading period) associated with the detected type.

func Do

func Do(client *http.Client, request *http.Request, retries *RetryConfig, access *AccessConfig) (*http.Response, error)

Do makes the given HTTP request using the current requestor and retry config

func NewRequest

func NewRequest(method string, url string, body io.Reader, headers map[string]string) (*http.Request, error)

NewRequest is a convenience method to create a request with the given headers

func ParseNetworks

func ParseNetworks(addrs ...string) ([]net.IP, []*net.IPNet, error)

ParseNetworks parses a list of IPs and IP networks (written in CIDR notation)

func ParseRetryAfter

func ParseRetryAfter(value string) time.Duration

ParseRetryAfter parses value of Retry-After headers which can be date or delay in seconds see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After

func ReplaceEscapedNulls

func ReplaceEscapedNulls(data string, repl string) string

replaces any `\u0000` sequences with the given replacement sequence which may be empty. A sequence such as `\\u0000` is preserved as it is an escaped slash followed by the sequence `u0000`

func SetRequestor

func SetRequestor(requestor Requestor)

SetRequestor sets the requestor used by Request

Types

type AccessConfig

type AccessConfig struct {
	ResolveTimeout time.Duration
	DisallowedIPs  []net.IP
	DisallowedNets []*net.IPNet
}

AccessConfig configures what can be accessed

func NewAccessConfig

func NewAccessConfig(resolveTimeout time.Duration, disallowedIPs []net.IP, disallowedNets []*net.IPNet) *AccessConfig

NewAccessConfig creates a new access config

func (*AccessConfig) Allow

func (c *AccessConfig) Allow(request *http.Request) (bool, error)

Allow determines whether the given request should be allowed

type Log

type Log struct {
	*LogWithoutTime
	CreatedOn time.Time `json:"created_on" validate:"required"`
}

Log is a single HTTP trace that can be serialized/deserialized to/from JSON.

func NewLog

func NewLog(trace *Trace, trimURLTo, trimTracesTo int, redact stringsx.Redactor) *Log

NewLog creates a new HTTP log from a trace

type LogWithoutTime

type LogWithoutTime struct {
	URL        string `json:"url" validate:"required"`
	StatusCode int    `json:"status_code,omitempty"`
	Request    string `json:"request" validate:"required"`
	Response   string `json:"response,omitempty"`
	ElapsedMS  int    `json:"elapsed_ms"`
	Retries    int    `json:"retries"`
}

LogWithoutTime is a single HTTP trace that can be serialized/deserialized to/from JSON. Note that this struct has no time component because it's intended to be embedded in something that does.

func NewLogWithoutTime

func NewLogWithoutTime(trace *Trace, trimURLTo, trimTracesTo int, redact stringsx.Redactor) *LogWithoutTime

NewLogWithoutTime creates a new log

type MockRequestor

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

MockRequestor is a requestor which can be mocked with responses for given URLs

func NewMockRequestor

func NewMockRequestor(mocks map[string][]*MockResponse) *MockRequestor

NewMockRequestor creates a new mock requestor with the given mocks

func (*MockRequestor) Clone

func (r *MockRequestor) Clone() *MockRequestor

Clone returns a clone of this requestor

func (*MockRequestor) Do

func (r *MockRequestor) Do(client *http.Client, request *http.Request) (*http.Response, error)

Do returns the mocked reponse for the given request

func (*MockRequestor) HasUnused

func (r *MockRequestor) HasUnused() bool

HasUnused returns true if there are unused mocks leftover

func (*MockRequestor) MarshalJSON

func (r *MockRequestor) MarshalJSON() ([]byte, error)

func (*MockRequestor) Requests

func (r *MockRequestor) Requests() []*http.Request

Requests returns the received requests

func (*MockRequestor) SetIgnoreLocal

func (r *MockRequestor) SetIgnoreLocal(ignore bool)

SetIgnoreLocal sets whether the requestor should ignore requests on localhost and delegate these the the default requestor.

func (*MockRequestor) UnmarshalJSON

func (r *MockRequestor) UnmarshalJSON(data []byte) error

type MockResponse

type MockResponse struct {
	Status       int
	Headers      map[string]string
	Body         []byte
	BodyIsString bool
	BodyRepeat   int
}

func NewMockResponse

func NewMockResponse(status int, headers map[string]string, body []byte) *MockResponse

NewMockResponse creates a new mock response

func (*MockResponse) Make

func (m *MockResponse) Make(request *http.Request) *http.Response

Make mocks making the given request and returning this as the response

func (*MockResponse) MarshalJSON

func (m *MockResponse) MarshalJSON() ([]byte, error)

func (*MockResponse) UnmarshalJSON

func (m *MockResponse) UnmarshalJSON(data []byte) error

type Recorder

type Recorder struct {
	Trace *Trace

	ResponseWriter http.ResponseWriter
	// contains filtered or unexported fields
}

Recorder is a utility for creating traces of HTTP requests being handled

func NewRecorder

func NewRecorder(r *http.Request, w http.ResponseWriter, reconstruct bool) (*Recorder, error)

NewRecorder creates a new recorder for an HTTP request. If `originalRequest` is true, it tries to reconstruct the original request object.

func (*Recorder) End

func (r *Recorder) End() error

End is called when the response has been written and generates the trace

type Requestor

type Requestor interface {
	Do(*http.Client, *http.Request) (*http.Response, error)
}

Requestor is anything that can make an HTTP request with a client

var DefaultRequestor Requestor = defaultRequestor{}

DefaultRequestor is the default HTTP requestor

type RetryConfig

type RetryConfig struct {
	Backoffs    []time.Duration
	Jitter      float64
	ShouldRetry func(*http.Request, *http.Response, time.Duration) bool
}

RetryConfig configures if and how retrying of requests happens

func NewExponentialRetries

func NewExponentialRetries(initialBackoff time.Duration, count int, jitter float64) *RetryConfig

NewExponentialRetries creates a new retry config with the given delays

func NewFixedRetries

func NewFixedRetries(backoffs ...time.Duration) *RetryConfig

NewFixedRetries creates a new retry config with the given backoffs

func (*RetryConfig) Backoff

func (r *RetryConfig) Backoff(n int) time.Duration

Backoff gets the backoff time for the nth retry

func (*RetryConfig) MaxRetries

func (r *RetryConfig) MaxRetries() int

MaxRetries gets the maximum number of retries allowed

type Trace

type Trace struct {
	Request       *http.Request
	RequestTrace  []byte
	Response      *http.Response
	ResponseTrace []byte
	ResponseBody  []byte // response body stored separately
	StartTime     time.Time
	EndTime       time.Time
	Retries       int
}

Trace holds the complete trace of an HTTP request/response

func DoTrace

func DoTrace(client *http.Client, request *http.Request, retries *RetryConfig, access *AccessConfig, maxBodyBytes int) (*Trace, error)

DoTrace makes the given request saving traces of the complete request and response.

• If the request is successful, the trace will have a response and response body
• If reading the body errors, the trace will have a response but no response body
• If connection fails, the trace will have a request but no response or response body

func (*Trace) SanitizedRequest

func (t *Trace) SanitizedRequest(placeholder string) string

SanitizedRequest returns a valid UTF-8 string version of the request, substituting the body with a placeholder if it isn't valid UTF-8. It also strips any NULL characters as not all external dependencies can handle those.

func (*Trace) SanitizedResponse

func (t *Trace) SanitizedResponse(placeholder string) string

SanitizedResponse returns a valid UTF-8 string version of the response, substituting the body with a placeholder if it isn't valid UTF-8. It also strips any NULL characters as not all external dependencies can handle those.

func (*Trace) String

func (t *Trace) String() string

type WebSocket

type WebSocket interface {
	// Start begins reading and writing of messages on this socket
	Start()

	// Send sends the given message over the socket
	Send([]byte)

	// Close closes the socket connection
	Close(int)

	// OnMessage is called when the socket receives a message
	OnMessage(func([]byte))

	// OnClose is called when the socket is closed (even if we initiate the close)
	OnClose(func(int))
}

WebSocket provides a websocket interface similar to that of Javascript.

func NewWebSocket

func NewWebSocket(w http.ResponseWriter, r *http.Request, maxReadBytes int64, sendBuffer int) (WebSocket, error)

NewWebSocket creates a new web socket from a regular HTTP request