Documentation
¶
Overview ¶
Package client provides a generic Client that wraps net/http.Client and follows standards within project's REST APIs.
It provides a way to configure exponential retries in Dialer with jitter easily configurable usual options and helper functions to be used in clients for HTTP APIs.
Index ¶
- Variables
- func NewHTTPClient(options *HTTPClientOptions) *http.Client
- type Client
- func (c Client) JSON(method, path string, query url.Values, body io.Reader, response interface{}) (err error)
- func (c Client) Request(method, path string, query url.Values, body io.Reader, accept []string) (resp *http.Response, err error)
- func (c Client) Stream(method, path string, query url.Values, body io.Reader, accept []string) (data io.ReadCloser, contentType string, err error)
- type Error
- type HTTPClientOptions
- type HTTPError
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultHTTPClient is an instance of net/http.Client that has // retry enabled and is used if Client.HTTPClient is nil. DefaultHTTPClient = NewHTTPClient(&HTTPClientOptions{ RetryTimeMax: 45 * time.Second, }) // DefaultKeyHeader is default HTTP header name to pass API key when // making a request. DefaultKeyHeader = "X-Key" )
Functions ¶
func NewHTTPClient ¶
func NewHTTPClient(options *HTTPClientOptions) *http.Client
NewHTTPClient creates a net/http.Client with options from HTTPClientOptions.
Types ¶
type Client ¶
type Client struct {
// Endpoint is an URL of the service. (required)
Endpoint string
// Key is a single string that is used in request authorization.
Key string
// KeyHeader is HTTP header name used to pass Client.Key value.
// If it is left blank, DefaultKeyHeader is used.
KeyHeader string
// UserAgent is a string that will be passed as a value to User-Agent
// HTTP header.
UserAgent string
// Headers is optional additional headers that will be passed on
// each request.
Headers map[string]string
// ErrorRegistry maps error codes to actual errors. It is used to
// identify errors from the services and pass them as return values.
ErrorRegistry map[int]error
// HTTPClient is net/http.Client to be used for making HTTP requests.
// If HTTPClient is nil, DefaultHTTPClient is used.
HTTPClient *http.Client
}
Client stores properties that defines communication with a HTTP API service.
func (Client) JSON ¶
func (c Client) JSON(method, path string, query url.Values, body io.Reader, response interface{}) (err error)
JSON makes a HTTP request that expects application/json response. It decodes response body to a `response` argument.
func (Client) Request ¶
func (c Client) Request(method, path string, query url.Values, body io.Reader, accept []string) (resp *http.Response, err error)
Request makes a HTTP request based on Client configuration and arguments provided.
func (Client) Stream ¶
func (c Client) Stream(method, path string, query url.Values, body io.Reader, accept []string) (data io.ReadCloser, contentType string, err error)
Stream makes a HTTP request and returns request body as io.ReadCloser, to be able to read long running responses. Returned io.ReadCloser must be closed at the end of read. To reuse HTTP connection, make sure that the whole data is read before closing it.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is a generic error in this package.
type HTTPClientOptions ¶
type HTTPClientOptions struct {
// Value for net.Dialer.Timeout.
Timeout time.Duration
// Value for net.Dialer.KeepAlive.
KeepAlive time.Duration `envconfig:"KEEP_ALIVE"`
// Value for net/http.Transport.TLSHandshakeTimeout.
TLSHandshakeTimeout time.Duration `envconfig:"TLS_HANDSHAKE_TIMEOUT"`
// Value for crypto/tls.Config.TLSSkipVerify.
TLSSkipVerify bool `envconfig:"TLS_SKIP_VERIFY"`
// Maximum time while Dialer reties are made.
// Default is 0. Which means that Retrying is disabled by default.
RetryTimeMax time.Duration `envconfig:"RETRY_TIME_MAX"`
// Maximum time between two retries.
// Default is 2 seconds.
RetrySleepMax time.Duration `envconfig:"RETRY_SLEEP_MAX"`
// Time for first retry. Every other is doubled until RetrySleepMax.
// Default is 200 milliseconds.
RetrySleepBase time.Duration `envconfig:"RETRY_SLEEP_BASE"`
}
HTTPClientOptions is structure that passes optional variables to NewHTTPClient.
func (HTTPClientOptions) MarshalJSON ¶
func (o HTTPClientOptions) MarshalJSON() ([]byte, error)
MarshalJSON implements of json.Marshaler interface. It marshals string representations of time.Duration.
func (*HTTPClientOptions) UnmarshalJSON ¶
func (o *HTTPClientOptions) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unamrshaler interface. It parses time.Duration as strings.
Source Files