clientlib

README

go-clientlib

Overview

go-clientlib is used to reduce much of the boilerplate needed for sending and receiving http requests and responses in client libraries.

Documentation

Index

• func DefaultErrorCheck(r *Request, doErr error, res *http.Response) error
• func DefaultErrorSummary(body []byte) string
• func DefaultRequestPrepare(*Request) error
• func DefaultResponseHandle(r *Request, res *http.Response) error
• func Do(ctx context.Context, method, urlStr string, opts ...RequestOption) (*http.Request, *http.Response, error)
• type ErrorCheck
• type ErrorSummary
• type Request
  • func New(ctx context.Context, method, urlStr string, opts ...RequestOption) (*Request, error)
  • func (r *Request) Do() (*http.Response, error)
  • func (r *Request) ErrorFields() map[string]interface{}
  • func (r *Request) SetBody(body io.Reader)
• type RequestOption
  • func DontClose() RequestOption
  • func RecvJSON(recvs interface{}) RequestOption
  • func RecvText(recvs *string) RequestOption
  • func RecvXML(recvs interface{}) RequestOption
  • func SendJSON(sends interface{}) RequestOption
  • func SendText(sends string) RequestOption
  • func SendXML(sends interface{}) RequestOption
• type RequestPrepare
• type ResponseHandle

Functions

func DefaultErrorCheck

func DefaultErrorCheck(r *Request, doErr error, res *http.Response) error

DefaultErrorCheck is the default error checker used if none is configured on a Request. doErr and res are the return values of executing http.Client.Do(), so any implementation should first check doErr for non-nill & react appropriately. If an http response was received, if a non-200 class status was also received, then the response body will be read (up to a const limit) and passed to request.ErrorSummary to attempt to parse out the error body, which will be passed as the "detail" flag on the returned error.

func DefaultErrorSummary

func DefaultErrorSummary(body []byte) string

DefaultErrorSummary just returns the string of the received error body. Note that the body passed in is potentially truncated before this call.

func DefaultRequestPrepare

func DefaultRequestPrepare(*Request) error

DefaultRequestPrepare does nothing.

func DefaultResponseHandle

func DefaultResponseHandle(r *Request, res *http.Response) error

DefaultResponseHandle merely closes the response body.

func Do

func Do(ctx context.Context, method, urlStr string, opts ...RequestOption) (*http.Request, *http.Response, error)

Do is a shortcut for creating and executing an http request.

Types

type ErrorCheck

type ErrorCheck func(r *Request, doErr error, res *http.Response) error

ErrorCheck is the signature for the function that is passed the error & response immediately from http.Client.Do().

type ErrorSummary

type ErrorSummary func([]byte) string

ErrorSummary is the signature for the function that is passed the fully read body of an error response.

type Request

type Request struct {
	*http.Request
	Client             *http.Client
	ErrorCheck         ErrorCheck
	ErrorBodyMaxLength int64
	ErrorSummary       ErrorSummary
	ResponseHandle     ResponseHandle
	RequestPrepare     RequestPrepare
}

Request encompasses an http.Request, plus configured behavior options.

func New

func New(ctx context.Context, method, urlStr string, opts ...RequestOption) (*Request, error)

New creates and returns a new Request, potentially configured via a vector of RequestOption's.

func (*Request) Do

func (r *Request) Do() (*http.Response, error)

Do executes the Request. The Request.ErrorCheck to determine if this attempt has failed, and transform the returned error. Otherwise, Request.ResponseHandler will examine the response. It's expected that the ResponseHandler has been configured via a RequestOption to perform response parsing and storing.

func (*Request) ErrorFields

func (r *Request) ErrorFields() map[string]interface{}

ErrorFields returns error annotation fields for the request.

func (*Request) SetBody

func (r *Request) SetBody(body io.Reader)

SetBody mirrors the ReadCloser config in http.NewRequest, ensuring that a ReadCloser is used for http.Request.Body.

type RequestOption

type RequestOption func(*Request)

RequestOption is the signature for functions that can perform some configuration of a Request.

func DontClose

func DontClose() RequestOption

DontClose sets the ResponseBody to an empty function, so that the response body is not automatically closed. Users of this should be sure to call res.Body.Close().

func RecvJSON

func RecvJSON(recvs interface{}) RequestOption

RecvJSON returns a RequestOption that will set the json headers on a request, and set a ResponseHandler that will unmarshal the response body to the given interface{}.

func RecvText

func RecvText(recvs *string) RequestOption

RecvText returns a RequestOption that will set the text headers on a request, and set a ResponseHandler that will unmarshal the response body to the given string.

func RecvXML

func RecvXML(recvs interface{}) RequestOption

RecvXML returns a RequestOption that will set the xml headers on a request, and set a ResponseHandler that will unmarshal the response body to the given interface{}.

func SendJSON

func SendJSON(sends interface{}) RequestOption

SendJSON returns a RequestOption that will marshal and set the json body & headers on a request.

func SendText

func SendText(sends string) RequestOption

SendText returns a RequestOption that will marshal and set the text body & headers on a request.

func SendXML

func SendXML(sends interface{}) RequestOption

SendXML returns a RequestOption that will marshal and set the xml body & headers on a request.

type RequestPrepare

type RequestPrepare func(r *Request) error

RequestPrepare is the signature for the function called before calling http.Client.Do, to perform any preparation needed before executing the request, eg. marshaling the body.

type ResponseHandle

type ResponseHandle func(*Request, *http.Response) error

ResponseHandle is the signature for the function called if ErrorCheck returns a nil error, and is responsible for performing any reads or stores from the request & response.