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) AppendRequestMiddleware(f RequestMiddleware)
  • func (c *Client) AppendResponseMiddleware(f ResponseMiddleware)
  • func (c *Client) ClearRequestMiddlewares()
  • func (c *Client) ClearResponseMiddlewares()
  • 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) GetUserAgent() string
  • func (c *Client) NewRequest(ctx context.Context, input RequestOptions) (*Request, error)
  • func (c *Client) SetAuthorizer(authorizer auth.Authorizer)
  • func (c *Client) SetUserAgent(userAgent string)
• 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 make the Do() method of retryablehttp client 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)

	// SetAuthorizer configures the request authorizer for the client
	SetAuthorizer(auth.Authorizer)

	// SetUserAgent configures the user agent to be included in requests
	SetUserAgent(string)

	// GetUserAgent retrieves the configured user agent for the client
	GetUserAgent() string

	// AppendRequestMiddleware appends a request middleware function for the client
	AppendRequestMiddleware(RequestMiddleware)

	// ClearRequestMiddlewares removes all request middleware functions for the client
	ClearRequestMiddlewares()

	// AppendResponseMiddleware appends a response middleware function for the client
	AppendResponseMiddleware(ResponseMiddleware)

	// ClearResponseMiddlewares removes all response middleware functions for the client
	ClearResponseMiddlewares()
}

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

	// AuthorizeRequest is an optional function to decorate a Request for authorization prior to being sent.
	// When nil, a standard Authorization header will be added using a bearer token as returned by the Token method
	// of the configured Authorizer. Define this function in order to customize the request authorization.
	AuthorizeRequest func(context.Context, *http.Request, auth.Authorizer) error

	// 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) AppendRequestMiddleware

func (c *Client) AppendRequestMiddleware(f RequestMiddleware)

AppendRequestMiddleware appends a request middleware function for the client

func (*Client) AppendResponseMiddleware

func (c *Client) AppendResponseMiddleware(f ResponseMiddleware)

AppendResponseMiddleware appends a response middleware function for the client

func (*Client) ClearRequestMiddlewares

func (c *Client) ClearRequestMiddlewares()

ClearRequestMiddlewares removes all request middleware functions for the client

func (*Client) ClearResponseMiddlewares

func (c *Client) ClearResponseMiddlewares()

ClearResponseMiddlewares removes all response middleware functions for the client

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) GetUserAgent

func (c *Client) GetUserAgent() string

GetUserAgent retrieves the configured user agent for the client

func (*Client) NewRequest

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

NewRequest configures a new *Request

func (*Client) SetAuthorizer

func (c *Client) SetAuthorizer(authorizer auth.Authorizer)

SetAuthorizer configures the request authorizer for the client

func (*Client) SetUserAgent

func (c *Client) SetUserAgent(userAgent string)

SetUserAgent configures the user agent to be included in requests

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

	// RetryFunc is an optional function to determine whether a request should be automatically retried
	RetryFunc RequestRetryFunc
}

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.