client

package
v0.20241126.1723 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 26, 2024 License: MPL-2.0 Imports: 20 Imported by: 9,313

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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

	CustomErrorParser ResponseErrorParser

	// 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 ResponseErrorParser 

type ResponseErrorParser interface {
	FromResponse(*http.Response) error
}

ResponseErrorParser is an optional custom parser that can parse an API error response to provide a friendly error

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.

Source Files

View all Source files

Directories

Path Synopsis
storage

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.