client

Documentation

Index

• func RequestRetryAll(retryFuncs ...RequestRetryFunc) func(resp *http.Response, o *odata.OData) (bool, error)
• func RequestRetryAny(retryFuncs ...RequestRetryFunc) func(resp *http.Response, o *odata.OData) (bool, error)
• func RetryOn404ConsistencyFailureFunc(resp *http.Response, _ *odata.OData) (bool, error)
• func RetryableErrorHandler(resp *http.Response, err error, _ int) (*http.Response, error)
• type BaseClient
• type Client
  • func NewClient(baseUri string, serviceName, apiVersion string) *Client
  • func (c *Client) Execute(ctx context.Context, req *Request) (*Response, error)
  • func (c *Client) ExecutePaged(ctx context.Context, req *Request) (*Response, error)
  • func (c *Client) NewRequest(ctx context.Context, input RequestOptions) (*Request, error)
• type Headers
  • func (h *Headers) Append(key, value string)
  • func (h *Headers) AppendHeader(h2 http.Header)
  • func (h *Headers) Headers() http.Header
  • func (h *Headers) Merge(h2 Headers)
• type Options
• type QueryParams
  • func (q *QueryParams) Append(key, value string)
  • func (q *QueryParams) AppendValues(q2 url.Values)
  • func (q *QueryParams) Merge(q2 Headers)
  • func (q *QueryParams) Values() url.Values
• type Request
  • func (r *Request) Execute(ctx context.Context) (*Response, error)
  • func (r *Request) ExecutePaged(ctx context.Context) (*Response, error)
  • func (r *Request) IsIdempotent() bool
  • func (r *Request) Marshal(payload interface{}) error
• type RequestMiddleware
• type RequestOptions
  • func (ro RequestOptions) Validate() error
• type RequestRetryFunc
• type Response
  • func (r *Response) Unmarshal(model interface{}) error
• type ResponseMiddleware
• type ValidStatusFunc

Functions

func RequestRetryAll

func RequestRetryAll(retryFuncs ...RequestRetryFunc) func(resp *http.Response, o *odata.OData) (bool, error)

RequestRetryAll wraps multiple RequestRetryFuncs and calls them in turn, only returning true if all funcs return true

func RequestRetryAny

func RequestRetryAny(retryFuncs ...RequestRetryFunc) func(resp *http.Response, o *odata.OData) (bool, error)

RequestRetryAny wraps multiple RequestRetryFuncs and calls them in turn, returning true if any func returns true

func RetryOn404ConsistencyFailureFunc

func RetryOn404ConsistencyFailureFunc(resp *http.Response, _ *odata.OData) (bool, error)

RetryOn404ConsistencyFailureFunc can be used to retry a request when a 404 response is received

func RetryableErrorHandler

func RetryableErrorHandler(resp *http.Response, err error, _ int) (*http.Response, error)

RetryableErrorHandler simply returns the resp and err, this is needed to makes the retryablehttp client's Do() return early with the response body not drained.

Types

type BaseClient

type BaseClient interface {
	// Execute invokes a non-paginated API request and returns a populated *Response
	Execute(ctx context.Context, req *Request) (*Response, error)

	// ExecutePaged invokes a paginated API request, merges the results from all pages and returns a populated *Response with all results
	ExecutePaged(ctx context.Context, req *Request) (*Response, error)

	// NewRequest constructs a *Request that can be passed to Execute or ExecutePaged
	NewRequest(ctx context.Context, input RequestOptions) (*Request, error)
}

type Client

type Client struct {
	// BaseUri is the base endpoint for this API.
	BaseUri string

	// UserAgent is the HTTP user agent string to send in requests.
	UserAgent string

	// CorrelationId is a custom correlation ID which can be added to requests for tracing purposes
	CorrelationId string

	// Authorizer is anything that can provide an access token with which to authorize requests.
	Authorizer auth.Authorizer

	// DisableRetries prevents the client from reattempting failed requests (which it does to work around eventual consistency issues).
	// This does not impact handling of retries related to rate limiting, which are always performed.
	DisableRetries bool

	// RequestMiddlewares is a slice of functions that are called in order before a request is sent
	RequestMiddlewares *[]RequestMiddleware

	// ResponseMiddlewares is a slice of functions that are called in order before a response is parsed and returned
	ResponseMiddlewares *[]ResponseMiddleware
}

Client is a base client to be used by API-specific clients. It satisfies the BaseClient interface.

func NewClient

func NewClient(baseUri string, serviceName, apiVersion string) *Client

NewClient returns a new Client configured with sensible defaults

func (*Client) Execute

func (c *Client) Execute(ctx context.Context, req *Request) (*Response, error)

Execute is used by the package to send an HTTP request to the API

func (*Client) ExecutePaged

func (c *Client) ExecutePaged(ctx context.Context, req *Request) (*Response, error)

ExecutePaged automatically pages through the results of Execute

func (*Client) NewRequest

func (c *Client) NewRequest(ctx context.Context, input RequestOptions) (*Request, error)

NewRequest configures a new *Request

type Headers

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

Headers is a representation of the HTTP headers to be sent with a Request

func (*Headers) Append

func (h *Headers) Append(key, value string)

Append sets a single header value

func (*Headers) AppendHeader

func (h *Headers) AppendHeader(h2 http.Header)

AppendHeader appends the http.Header values

func (*Headers) Headers

func (h *Headers) Headers() http.Header

Headers returns an http.Headers map containing header values

func (*Headers) Merge

func (h *Headers) Merge(h2 Headers)

Merge copies the header values from h2, overwriting as necessary

type Options

type Options interface {
	// ToHeaders yields a custom Headers struct to be appended to the request
	ToHeaders() *Headers

	// ToOData yields a custom *odata.Query struct to be appended to the request
	ToOData() *odata.Query

	// ToQuery yields a custom *QueryParams struct to be appended to the request
	ToQuery() *QueryParams
}

type QueryParams

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

QueryParams is a representation of the URL query parameters to be sent with a Request

func (*QueryParams) Append

func (q *QueryParams) Append(key, value string)

Append sets a single query parameter value

func (*QueryParams) AppendValues

func (q *QueryParams) AppendValues(q2 url.Values)

AppendValues appends the url.Values values

func (*QueryParams) Merge

func (q *QueryParams) Merge(q2 Headers)

Merge copies the query parameter values from q2, overwriting as necessary

func (*QueryParams) Values

func (q *QueryParams) Values() url.Values

Values returns a url.Values map containing query parameter values

type Request

type Request struct {
	RetryFunc        RequestRetryFunc
	ValidStatusCodes []int
	ValidStatusFunc  ValidStatusFunc

	Client BaseClient
	Pager  odata.CustomPager

	// Embed *http.Request so that we can send this to an *http.Client
	*http.Request
}

Request embeds *http.Request and adds useful metadata

func (*Request) Execute

func (r *Request) Execute(ctx context.Context) (*Response, error)

Execute invokes the Execute method for the Request's Client

func (*Request) ExecutePaged

func (r *Request) ExecutePaged(ctx context.Context) (*Response, error)

ExecutePaged invokes the ExecutePaged method for the Request's Client

func (*Request) IsIdempotent

func (r *Request) IsIdempotent() bool

IsIdempotent determines whether a Request can be safely retried when encountering a connection failure

func (*Request) Marshal

func (r *Request) Marshal(payload interface{}) error

Marshal serializes a payload body and adds it to the *Request

type RequestMiddleware

type RequestMiddleware func(*http.Request) (*http.Request, error)

RequestMiddleware can manipulate or log a request before it is sent

type RequestOptions

type RequestOptions struct {
	// ContentType is the content type of the request and should include the charset
	ContentType string

	// ExpectedStatusCodes is a slice of HTTP response codes considered valid for this request
	ExpectedStatusCodes []int

	// HttpMethod is the capitalized method verb for this request
	HttpMethod string

	// OptionsObject is used for dynamically modifying the request at runtime
	OptionsObject Options

	// Pager is an optional struct for handling custom pagination for this request. OData 4.0 compliant paging
	// is already handled implicitly and does not require a custom pager.
	Pager odata.CustomPager

	// Path is the absolute URI for this request, with a leading slash.
	Path string
}

func (RequestOptions) Validate

func (ro RequestOptions) Validate() error

type RequestRetryFunc

type RequestRetryFunc func(*http.Response, *odata.OData) (bool, error)

RequestRetryFunc is a function that determines whether an HTTP request has failed due to eventual consistency and should be retried

type Response

type Response struct {
	OData *odata.OData

	// Embed *http.Response
	*http.Response
}

Response embeds *http.Response and adds useful methods

func (*Response) Unmarshal

func (r *Response) Unmarshal(model interface{}) error

Unmarshal deserializes a response body into the provided model

type ResponseMiddleware

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

ResponseMiddleware can manipulate or log a response before it is parsed and returned

type ValidStatusFunc

type ValidStatusFunc func(*http.Response, *odata.OData) bool

ValidStatusFunc is a function that tests whether an HTTP response is considered valid for the particular request.