const (
// HeaderLocation specifies the HTTP Location header.
HeaderLocation = "Location"
// HeaderRetryAfter specifies the HTTP Retry-After header.
HeaderRetryAfter = "Retry-After"
)
const (
// DefaultPollingDelay is a reasonable delay between polling requests.
DefaultPollingDelay = 30 * time.Second
// DefaultPollingDuration is a reasonable total polling duration.
DefaultPollingDuration = 15 * time.Minute
// DefaultRetryAttempts is number of attempts for retry status codes (5xx).
DefaultRetryAttempts = 3
// DefaultRetryDuration is the duration to wait between retries.
DefaultRetryDuration = 30 * time.Second
)
const (
// UndefinedStatusCode is used when HTTP status code is not available for an error.
UndefinedStatusCode = 0
)
Count429AsRetry indicates that a 429 response should be included as a retry attempt.
var Count429AsRetry = true
Max429Delay is the maximum duration to wait between retries on a 429 if no Retry-After header was received.
var Max429Delay time.Duration
var (
// StatusCodesForRetry are a defined group of status code for which the client will retry
StatusCodesForRetry = []int{
http.StatusRequestTimeout,
http.StatusTooManyRequests,
http.StatusInternalServerError,
http.StatusBadGateway,
http.StatusServiceUnavailable,
http.StatusGatewayTimeout,
}
)
func AsStringSlice(s interface{}) ([]string, error)
AsStringSlice method converts interface{} to []string. s must be of type slice or array or an error is returned. Each element of s will be converted to its string representation.
▹ Example
func ChangeToGet(req *http.Request) *http.Request
ChangeToGet turns the specified http.Request into a GET (it assumes it wasn't). This is mainly useful for long-running operations that use the Azure-AsyncOperation header, so we change the initial PUT into a GET to retrieve the final result.
func CopyAndDecode(encodedAs EncodedAs, r io.Reader, v interface{}) (b bytes.Buffer, err error)
CopyAndDecode decodes the data from the passed io.Reader while making a copy. Having a copy is especially useful if there is a chance the data will fail to decode. encodedAs specifies the expected encoding, r provides the io.Reader to the data, and v is the decoding destination.
func DelayForBackoff(backoff time.Duration, attempt int, cancel <-chan struct{}) bool
DelayForBackoff invokes time.After for the supplied backoff duration raised to the power of passed attempt (i.e., an exponential backoff delay). Backoff duration is in seconds and can set to zero for no delay. The delay may be canceled by closing the passed channel. If terminated early, returns false. Note: Passing attempt 1 will result in doubling "backoff" duration. Treat this as a zero-based attempt count.
func DelayForBackoffWithCap(backoff, cap time.Duration, attempt int, cancel <-chan struct{}) bool
DelayForBackoffWithCap invokes time.After for the supplied backoff duration raised to the power of passed attempt (i.e., an exponential backoff delay). Backoff duration is in seconds and can set to zero for no delay. To cap the maximum possible delay specify a value greater than zero for cap. The delay may be canceled by closing the passed channel. If terminated early, returns false. Note: Passing attempt 1 will result in doubling "backoff" duration. Treat this as a zero-based attempt count.
func DelayWithRetryAfter(resp *http.Response, cancel <-chan struct{}) bool
DelayWithRetryAfter invokes time.After for the duration specified in the "Retry-After" header. The value of Retry-After can be either the number of seconds or a date in RFC1123 format. The function returns true after successfully waiting for the specified duration. If there is no Retry-After header or the wait is cancelled the return value is false.
func DrainResponseBody(resp *http.Response) error
DrainResponseBody reads the response body then closes it.
func Encode(location string, v interface{}, sep ...string) string
Encode method encodes url path and query parameters.
func ExtractHeader(header string, resp *http.Response) []string
ExtractHeader extracts all values of the specified header from the http.Response. It returns an empty string slice if the passed http.Response is nil or the header does not exist.
func ExtractHeaderValue(header string, resp *http.Response) string
ExtractHeaderValue extracts the first value of the specified header from the http.Response. It returns an empty string if the passed http.Response is nil or the header does not exist.
func GetLocation(resp *http.Response) string
GetLocation retrieves the URL from the Location header of the passed response.
func GetRetryAfter(resp *http.Response, defaultDelay time.Duration) time.Duration
GetRetryAfter extracts the retry delay from the Retry-After header of the passed response. If the header is absent or is malformed, it will return the supplied default delay time.Duration.
func IsTemporaryNetworkError(err error) bool
IsTemporaryNetworkError returns true if the specified error is a temporary network error or false if it's not. If the error doesn't implement the net.Error interface the return value is true.
func IsTokenRefreshError(err error) bool
IsTokenRefreshError returns true if the specified error implements the TokenRefreshError interface.
func MapToValues(m map[string]interface{}) url.Values
MapToValues method converts map[string]interface{} to url.Values.
func NewPollingRequest(resp *http.Response, cancel <-chan struct{}) (*http.Request, error)
NewPollingRequest allocates and returns a new http.Request to poll for the passed response.
func NewPollingRequestWithContext(ctx context.Context, resp *http.Response) (*http.Request, error)
NewPollingRequestWithContext allocates and returns a new http.Request with the specified context to poll for the passed response.
func Prepare(r *http.Request, decorators ...PrepareDecorator) (*http.Request, error)
Prepare accepts an http.Request and a, possibly empty, set of PrepareDecorators. It creates a Preparer from the decorators which it then applies to the passed http.Request.
▹ Example
func Respond(r *http.Response, decorators ...RespondDecorator) error
Respond accepts an http.Response and a, possibly empty, set of RespondDecorators. It creates a Responder from the decorators it then applies to the passed http.Response.
func ResponseHasStatusCode(resp *http.Response, codes ...int) bool
ResponseHasStatusCode returns true if the status code in the HTTP Response is in the passed set and false otherwise.
func Send(r *http.Request, decorators ...SendDecorator) (*http.Response, error)
Send sends, by means of the default http.Client, the passed http.Request, returning the http.Response and possible error. It also accepts a, possibly empty, set of SendDecorators which it will apply the http.Client before invoking the Do method.
Send is a convenience method and not recommended for production. Advanced users should use SendWithSender, passing and sharing their own Sender (e.g., instance of http.Client).
Send will not poll or retry requests.
func SendWithSender(s Sender, r *http.Request, decorators ...SendDecorator) (*http.Response, error)
SendWithSender sends the passed http.Request, through the provided Sender, returning the http.Response and possible error. It also accepts a, possibly empty, set of SendDecorators which it will apply the http.Client before invoking the Do method.
SendWithSender will not poll or retry requests.
▹ Example
func String(v interface{}, sep ...string) string
String method converts interface v to string. If interface is a list, it joins list elements using the separator. Note that only sep[0] will be used for joining if any separator is specified.
▹ Example
func TeeReadCloser(rc io.ReadCloser, w io.Writer) io.ReadCloser
TeeReadCloser returns a ReadCloser that writes to w what it reads from rc. It utilizes io.TeeReader to copy the data read and has the same behavior when reading. Further, when it is closed, it ensures that rc is closed as well.
func UserAgent() string
UserAgent returns a string containing the Go version, system architecture and OS, and the go-autorest version.
func Version() string
Version returns the semantic version (see http://semver.org).
func WithPrepareDecorators(ctx context.Context, prepareDecorator []PrepareDecorator) context.Context
WithPrepareDecorators adds the specified PrepareDecorators to the provided context. If no PrepareDecorators are provided the context is unchanged.
func WithSendDecorators(ctx context.Context, sendDecorator []SendDecorator) context.Context
WithSendDecorators adds the specified SendDecorators to the provided context. If no SendDecorators are provided the context is unchanged.
APIKeyAuthorizer implements API Key authorization.
type APIKeyAuthorizer struct {
// contains filtered or unexported fields
}
func NewAPIKeyAuthorizer(headers map[string]interface{}, queryParameters map[string]interface{}) *APIKeyAuthorizer
NewAPIKeyAuthorizer creates an ApiKeyAuthorizer with headers.
func NewAPIKeyAuthorizerWithHeaders(headers map[string]interface{}) *APIKeyAuthorizer
NewAPIKeyAuthorizerWithHeaders creates an ApiKeyAuthorizer with headers.
func NewAPIKeyAuthorizerWithQueryParameters(queryParameters map[string]interface{}) *APIKeyAuthorizer
NewAPIKeyAuthorizerWithQueryParameters creates an ApiKeyAuthorizer with query parameters.
func (aka *APIKeyAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds an HTTP headers and Query Parameters.
Authorizer is the interface that provides a PrepareDecorator used to supply request authorization. Most often, the Authorizer decorator runs last so it has access to the full state of the formed HTTP request.
type Authorizer interface {
WithAuthorization() PrepareDecorator
}
BasicAuthorizer implements basic HTTP authorization by adding the Authorization HTTP header with the value "Basic <TOKEN>" where <TOKEN> is a base64-encoded username:password tuple.
type BasicAuthorizer struct {
// contains filtered or unexported fields
}
func NewBasicAuthorizer(userName, password string) *BasicAuthorizer
NewBasicAuthorizer creates a new BasicAuthorizer with the specified username and password.
func (ba *BasicAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds an HTTP Authorization header whose value is "Basic " followed by the base64-encoded username:password tuple.
BearerAuthorizer implements the bearer authorization
type BearerAuthorizer struct {
// contains filtered or unexported fields
}
func NewBearerAuthorizer(tp adal.OAuthTokenProvider) *BearerAuthorizer
NewBearerAuthorizer crates a BearerAuthorizer using the given token provider
func (ba *BearerAuthorizer) TokenProvider() adal.OAuthTokenProvider
TokenProvider returns OAuthTokenProvider so that it can be used for authorization outside the REST.
func (ba *BearerAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds an HTTP Authorization header whose value is "Bearer " followed by the token.
By default, the token will be automatically refreshed through the Refresher interface.
BearerAuthorizerCallback implements bearer authorization via a callback.
type BearerAuthorizerCallback struct {
// contains filtered or unexported fields
}
func NewBearerAuthorizerCallback(s Sender, callback BearerAuthorizerCallbackFunc) *BearerAuthorizerCallback
NewBearerAuthorizerCallback creates a bearer authorization callback. The callback is invoked when the HTTP request is submitted.
func (bacb *BearerAuthorizerCallback) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds an HTTP Authorization header whose value is "Bearer " followed by the token. The BearerAuthorizer is obtained via a user-supplied callback.
By default, the token will be automatically refreshed through the Refresher interface.
BearerAuthorizerCallbackFunc is the authentication callback signature.
type BearerAuthorizerCallbackFunc func(tenantID, resource string) (*BearerAuthorizer, error)
Client is the base for autorest generated clients. It provides default, "do nothing" implementations of an Authorizer, RequestInspector, and ResponseInspector. It also returns the standard, undecorated http.Client as a default Sender.
Generated clients should also use Error (see NewError and NewErrorWithError) for errors and return responses that compose with Response.
Most customization of generated clients is best achieved by supplying a custom Authorizer, custom RequestInspector, and / or custom ResponseInspector. Users may log requests, implement circuit breakers (see https://msdn.microsoft.com/en-us/library/dn589784.aspx) or otherwise influence sending the request by providing a decorated Sender.
type Client struct {
Authorizer Authorizer
Sender Sender
RequestInspector PrepareDecorator
ResponseInspector RespondDecorator
// PollingDelay sets the polling frequency used in absence of a Retry-After HTTP header
PollingDelay time.Duration
// PollingDuration sets the maximum polling time after which an error is returned.
// Setting this to zero will use the provided context to control the duration.
PollingDuration time.Duration
// RetryAttempts sets the total number of times the client will attempt to make an HTTP request.
// Set the value to 1 to disable retries. DO NOT set the value to less than 1.
RetryAttempts int
// RetryDuration sets the delay duration for retries.
RetryDuration time.Duration
// UserAgent, if not empty, will be set as the HTTP User-Agent header on all requests sent
// through the Do method.
UserAgent string
Jar http.CookieJar
// Set to true to skip attempted registration of resource providers (false by default).
SkipResourceProviderRegistration bool
// SendDecorators can be used to override the default chain of SendDecorators.
// This can be used to specify things like a custom retry SendDecorator.
// Set this to an empty slice to use no SendDecorators.
SendDecorators []SendDecorator
}
func NewClientWithOptions(options ClientOptions) Client
NewClientWithOptions returns an instance of a Client with the specified values.
func NewClientWithUserAgent(ua string) Client
NewClientWithUserAgent returns an instance of a Client with the UserAgent set to the passed string.
func (c *Client) AddToUserAgent(extension string) error
AddToUserAgent adds an extension to the current user agent
func (c Client) ByInspecting() RespondDecorator
ByInspecting is a convenience method that passes the response to the supplied ResponseInspector, if present, or returns the ByIgnoring RespondDecorator otherwise.
func (c Client) Do(r *http.Request) (*http.Response, error)
Do implements the Sender interface by invoking the active Sender after applying authorization. If Sender is not set, it uses a new instance of http.Client. In both cases it will, if UserAgent is set, apply set the User-Agent header.
func (c Client) Send(req *http.Request, decorators ...SendDecorator) (*http.Response, error)
Send sends the provided http.Request using the client's Sender or the default sender. It returns the http.Response and possible error. It also accepts a, possibly empty, default set of SendDecorators used when sending the request. SendDecorators have the following precedence: 1. In a request's context via WithSendDecorators() 2. Specified on the client in SendDecorators 3. The default values specified in this method
func (c Client) WithAuthorization() PrepareDecorator
WithAuthorization is a convenience method that returns the WithAuthorization PrepareDecorator from the current Authorizer. If not Authorizer is set, it uses the NullAuthorizer.
func (c Client) WithInspection() PrepareDecorator
WithInspection is a convenience method that passes the request to the supplied RequestInspector, if present, or returns the WithNothing PrepareDecorator otherwise.
ClientOptions contains various Client configuration options.
type ClientOptions struct {
// UserAgent is an optional user-agent string to append to the default user agent.
UserAgent string
// Renegotiation is an optional setting to control client-side TLS renegotiation.
Renegotiation tls.RenegotiationSupport
}
CognitiveServicesAuthorizer implements authorization for Cognitive Services.
type CognitiveServicesAuthorizer struct {
// contains filtered or unexported fields
}
func NewCognitiveServicesAuthorizer(subscriptionKey string) *CognitiveServicesAuthorizer
NewCognitiveServicesAuthorizer is
func (csa *CognitiveServicesAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization is
Decoder defines the decoding method json.Decoder and xml.Decoder share
type Decoder interface {
Decode(v interface{}) error
}
func NewDecoder(encodedAs EncodedAs, r io.Reader) Decoder
NewDecoder creates a new decoder appropriate to the passed encoding. encodedAs specifies the type of encoding and r supplies the io.Reader containing the encoded data.
DetailedError encloses a error with details of the package, method, and associated HTTP status code (if any).
type DetailedError struct {
Original error
// PackageType is the package type of the object emitting the error. For types, the value
// matches that produced the the '%T' format specifier of the fmt package. For other elements,
// such as functions, it is just the package name (e.g., "autorest").
PackageType string
// Method is the name of the method raising the error.
Method string
// StatusCode is the HTTP Response StatusCode (if non-zero) that led to the error.
StatusCode interface{}
// Message is the error message.
Message string
// Service Error is the response body of failed API in bytes
ServiceError []byte
// Response is the response object that was returned during failure if applicable.
Response *http.Response
}
func NewError(packageType string, method string, message string, args ...interface{}) DetailedError
NewError creates a new Error conforming object from the passed packageType, method, and message. message is treated as a format string to which the optional args apply.
func NewErrorWithError(original error, packageType string, method string, resp *http.Response, message string, args ...interface{}) DetailedError
NewErrorWithError creates a new Error conforming object from the passed packageType, method, statusCode of the given resp (UndefinedStatusCode if resp is nil), message, and original error. message is treated as a format string to which the optional args apply.
func NewErrorWithResponse(packageType string, method string, resp *http.Response, message string, args ...interface{}) DetailedError
NewErrorWithResponse creates a new Error conforming object from the passed packageType, method, statusCode of the given resp (UndefinedStatusCode if resp is nil), and message. message is treated as a format string to which the optional args apply.
func (e DetailedError) Error() string
Error returns a formatted containing all available details (i.e., PackageType, Method, StatusCode, Message, and original error (if any)).
func (e DetailedError) Unwrap() error
Unwrap returns the original error.
EncodedAs is a series of constants specifying various data encodings
type EncodedAs string
const (
// EncodedAsJSON states that data is encoded as JSON
EncodedAsJSON EncodedAs = "JSON"
// EncodedAsXML states that data is encoded as Xml
EncodedAsXML EncodedAs = "XML"
)
EventGridKeyAuthorizer implements authorization for event grid using key authentication.
type EventGridKeyAuthorizer struct {
// contains filtered or unexported fields
}
func NewEventGridKeyAuthorizer(topicKey string) EventGridKeyAuthorizer
NewEventGridKeyAuthorizer creates a new EventGridKeyAuthorizer with the specified topic key.
func (egta EventGridKeyAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds the aeg-sas-key authentication header.
LoggingInspector implements request and response inspectors that log the full request and response to a supplied log.
type LoggingInspector struct {
Logger *log.Logger
}
func (li LoggingInspector) ByInspecting() RespondDecorator
ByInspecting returns a RespondDecorator that emits the http.Response to the supplied logger. The body is restored after being emitted.
Note: Since it reads the entire Body, this decorator should not be used where body streaming is important. It is best used to trace JSON or similar body values.
func (li LoggingInspector) WithInspection() PrepareDecorator
WithInspection returns a PrepareDecorator that emits the http.Request to the supplied logger. The body is restored after being emitted.
Note: Since it reads the entire Body, this decorator should not be used where body streaming is important. It is best used to trace JSON or similar body values.
MultiTenantBearerAuthorizer implements bearer authorization across multiple tenants.
type MultiTenantBearerAuthorizer struct {
// contains filtered or unexported fields
}
func NewMultiTenantBearerAuthorizer(tp adal.MultitenantOAuthTokenProvider) *MultiTenantBearerAuthorizer
NewMultiTenantBearerAuthorizer creates a MultiTenantBearerAuthorizer using the given token provider.
func (mt *MultiTenantBearerAuthorizer) TokenProvider() adal.MultitenantOAuthTokenProvider
TokenProvider returns the underlying MultitenantOAuthTokenProvider for this authorizer.
func (mt *MultiTenantBearerAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds an HTTP Authorization header using the primary token along with the auxiliary authorization header using the auxiliary tokens.
By default, the token will be automatically refreshed through the Refresher interface.
MultiTenantServicePrincipalTokenAuthorizer provides authentication across tenants.
type MultiTenantServicePrincipalTokenAuthorizer interface {
WithAuthorization() PrepareDecorator
}
func NewMultiTenantServicePrincipalTokenAuthorizer(tp adal.MultitenantOAuthTokenProvider) MultiTenantServicePrincipalTokenAuthorizer
NewMultiTenantServicePrincipalTokenAuthorizer crates a BearerAuthorizer using the given token provider
NullAuthorizer implements a default, "do nothing" Authorizer.
type NullAuthorizer struct{}
func (na NullAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that does nothing.
PrepareDecorator takes and possibly decorates, by wrapping, a Preparer. Decorators may affect the http.Request and pass it along or, first, pass the http.Request along then affect the result.
type PrepareDecorator func(Preparer) Preparer
▹ Example
▹ Example (Pre)
func AsContentType(contentType string) PrepareDecorator
AsContentType returns a PrepareDecorator that adds an HTTP Content-Type header whose value is the passed contentType.
func AsDelete() PrepareDecorator
AsDelete returns a PrepareDecorator that sets the HTTP method to DELETE.
func AsFormURLEncoded() PrepareDecorator
AsFormURLEncoded returns a PrepareDecorator that adds an HTTP Content-Type header whose value is "application/x-www-form-urlencoded".
func AsGet() PrepareDecorator
AsGet returns a PrepareDecorator that sets the HTTP method to GET.
func AsHead() PrepareDecorator
AsHead returns a PrepareDecorator that sets the HTTP method to HEAD.
func AsJSON() PrepareDecorator
AsJSON returns a PrepareDecorator that adds an HTTP Content-Type header whose value is "application/json".
func AsMerge() PrepareDecorator
AsMerge returns a PrepareDecorator that sets the HTTP method to MERGE.
func AsOctetStream() PrepareDecorator
AsOctetStream returns a PrepareDecorator that adds the "application/octet-stream" Content-Type header.
func AsOptions() PrepareDecorator
AsOptions returns a PrepareDecorator that sets the HTTP method to OPTIONS.
func AsPatch() PrepareDecorator
AsPatch returns a PrepareDecorator that sets the HTTP method to PATCH.
func AsPost() PrepareDecorator
AsPost returns a PrepareDecorator that sets the HTTP method to POST.
func AsPut() PrepareDecorator
AsPut returns a PrepareDecorator that sets the HTTP method to PUT.
func GetPrepareDecorators(ctx context.Context, defaultPrepareDecorators ...PrepareDecorator) []PrepareDecorator
GetPrepareDecorators returns the PrepareDecorators in the provided context or the provided default PrepareDecorators.
func WithBaseURL(baseURL string) PrepareDecorator
WithBaseURL returns a PrepareDecorator that populates the http.Request with a url.URL constructed from the supplied baseUrl. Query parameters will be encoded as required.
▹ Example
func WithBearerAuthorization(token string) PrepareDecorator
WithBearerAuthorization returns a PrepareDecorator that adds an HTTP Authorization header whose value is "Bearer " followed by the supplied token.
func WithBool(v bool) PrepareDecorator
WithBool returns a PrepareDecorator that encodes the passed bool into the body of the request and sets the Content-Length header.
func WithBytes(input *[]byte) PrepareDecorator
WithBytes returns a PrepareDecorator that takes a list of bytes which passes the bytes directly to the body
func WithCustomBaseURL(baseURL string, urlParameters map[string]interface{}) PrepareDecorator
WithCustomBaseURL returns a PrepareDecorator that replaces brace-enclosed keys within the request base URL (i.e., http.Request.URL) with the corresponding values from the passed map.
▹ Example
func WithEscapedPathParameters(path string, pathParameters map[string]interface{}) PrepareDecorator
WithEscapedPathParameters returns a PrepareDecorator that replaces brace-enclosed keys within the request path (i.e., http.Request.URL.Path) with the corresponding values from the passed map. The values will be escaped (aka URL encoded) before insertion into the path.
▹ Example
func WithFile(f io.ReadCloser) PrepareDecorator
WithFile returns a PrepareDecorator that sends file in request body.
func WithFloat32(v float32) PrepareDecorator
WithFloat32 returns a PrepareDecorator that encodes the passed float32 into the body of the request and sets the Content-Length header.
func WithFloat64(v float64) PrepareDecorator
WithFloat64 returns a PrepareDecorator that encodes the passed float64 into the body of the request and sets the Content-Length header.
func WithFormData(v url.Values) PrepareDecorator
WithFormData returns a PrepareDecoratore that "URL encodes" (e.g., bar=baz&foo=quux) into the http.Request body.
▹ Example
func WithHeader(header string, value string) PrepareDecorator
WithHeader returns a PrepareDecorator that sets the specified HTTP header of the http.Request to the passed value. It canonicalizes the passed header name (via http.CanonicalHeaderKey) before adding the header.
▹ Example
func WithHeaders(headers map[string]interface{}) PrepareDecorator
WithHeaders returns a PrepareDecorator that sets the specified HTTP headers of the http.Request to the passed value. It canonicalizes the passed headers name (via http.CanonicalHeaderKey) before adding them.
func WithInt32(v int32) PrepareDecorator
WithInt32 returns a PrepareDecorator that encodes the passed int32 into the body of the request and sets the Content-Length header.
func WithInt64(v int64) PrepareDecorator
WithInt64 returns a PrepareDecorator that encodes the passed int64 into the body of the request and sets the Content-Length header.
func WithJSON(v interface{}) PrepareDecorator
WithJSON returns a PrepareDecorator that encodes the data passed as JSON into the body of the request and sets the Content-Length header.
▹ Example
func WithMethod(method string) PrepareDecorator
WithMethod returns a PrepareDecorator that sets the HTTP method of the passed request. The decorator does not validate that the passed method string is a known HTTP method.
func WithMultiPartFormData(formDataParameters map[string]interface{}) PrepareDecorator
WithMultiPartFormData returns a PrepareDecoratore that "URL encodes" (e.g., bar=baz&foo=quux) form parameters into the http.Request body.
func WithNothing() PrepareDecorator
WithNothing returns a "do nothing" PrepareDecorator that makes no changes to the passed http.Request.
func WithPath(path string) PrepareDecorator
WithPath returns a PrepareDecorator that adds the supplied path to the request URL. If the path is absolute (that is, it begins with a "/"), it replaces the existing path.
func WithPathParameters(path string, pathParameters map[string]interface{}) PrepareDecorator
WithPathParameters returns a PrepareDecorator that replaces brace-enclosed keys within the request path (i.e., http.Request.URL.Path) with the corresponding values from the passed map.
▹ Example
func WithQueryParameters(queryParameters map[string]interface{}) PrepareDecorator
WithQueryParameters returns a PrepareDecorators that encodes and applies the query parameters given in the supplied map (i.e., key=value).
▹ Example
func WithString(v string) PrepareDecorator
WithString returns a PrepareDecorator that encodes the passed string into the body of the request and sets the Content-Length header.
func WithUserAgent(ua string) PrepareDecorator
WithUserAgent returns a PrepareDecorator that adds an HTTP User-Agent header whose value is the passed string.
func WithXML(v interface{}) PrepareDecorator
WithXML returns a PrepareDecorator that encodes the data passed as XML into the body of the request and sets the Content-Length header.
▹ Example
Preparer is the interface that wraps the Prepare method.
Prepare accepts and possibly modifies an http.Request (e.g., adding Headers). Implementations must ensure to not share or hold per-invocation state since Preparers may be shared and re-used.
type Preparer interface {
Prepare(*http.Request) (*http.Request, error)
}
func CreatePreparer(decorators ...PrepareDecorator) Preparer
CreatePreparer creates, decorates, and returns a Preparer. Without decorators, the returned Preparer returns the passed http.Request unmodified. Preparers are safe to share and re-use.
▹ Example
▹ Example (Chain)
▹ Example (Multiple)
func DecoratePreparer(p Preparer, decorators ...PrepareDecorator) Preparer
DecoratePreparer accepts a Preparer and a, possibly empty, set of PrepareDecorators, which it applies to the Preparer. Decorators are applied in the order received, but their affect upon the request depends on whether they are a pre-decorator (change the http.Request and then pass it along) or a post-decorator (pass the http.Request along and alter it on return).
PreparerFunc is a method that implements the Preparer interface.
type PreparerFunc func(*http.Request) (*http.Request, error)
func (pf PreparerFunc) Prepare(r *http.Request) (*http.Request, error)
Prepare implements the Preparer interface on PreparerFunc.
RespondDecorator takes and possibly decorates, by wrapping, a Responder. Decorators may react to the http.Response and pass it along or, first, pass the http.Response along then react.
type RespondDecorator func(Responder) Responder
func ByClosing() RespondDecorator
ByClosing returns a RespondDecorator that first invokes the passed Responder after which it closes the response body. Since the passed Responder is invoked prior to closing the response body, the decorator may occur anywhere within the set.
func ByClosingIfError() RespondDecorator
ByClosingIfError returns a RespondDecorator that first invokes the passed Responder after which it closes the response if the passed Responder returns an error and the response body exists.
func ByCopying(b *bytes.Buffer) RespondDecorator
ByCopying copies the contents of the http.Response Body into the passed bytes.Buffer as the Body is read.
func ByDiscardingBody() RespondDecorator
ByDiscardingBody returns a RespondDecorator that first invokes the passed Responder after which it copies the remaining bytes (if any) in the response body to ioutil.Discard. Since the passed Responder is invoked prior to discarding the response body, the decorator may occur anywhere within the set.
func ByIgnoring() RespondDecorator
ByIgnoring returns a RespondDecorator that ignores the passed http.Response passing it unexamined to the next RespondDecorator.
func ByUnmarshallingBytes(v *[]byte) RespondDecorator
ByUnmarshallingBytes returns a RespondDecorator that copies the Bytes returned in the response Body into the value pointed to by v.
func ByUnmarshallingJSON(v interface{}) RespondDecorator
ByUnmarshallingJSON returns a RespondDecorator that decodes a JSON document returned in the response Body into the value pointed to by v.
▹ Example
func ByUnmarshallingXML(v interface{}) RespondDecorator
ByUnmarshallingXML returns a RespondDecorator that decodes a XML document returned in the response Body into the value pointed to by v.
▹ Example
func WithErrorUnlessOK() RespondDecorator
WithErrorUnlessOK returns a RespondDecorator that emits an error if the response StatusCode is anything other than HTTP 200.
▹ Example
func WithErrorUnlessStatusCode(codes ...int) RespondDecorator
WithErrorUnlessStatusCode returns a RespondDecorator that emits an error unless the response StatusCode is among the set passed. On error, response body is fully read into a buffer and presented in the returned error, as well as in the response body.
Responder is the interface that wraps the Respond method.
Respond accepts and reacts to an http.Response. Implementations must ensure to not share or hold state since Responders may be shared and re-used.
type Responder interface {
Respond(*http.Response) error
}
func CreateResponder(decorators ...RespondDecorator) Responder
CreateResponder creates, decorates, and returns a Responder. Without decorators, the returned Responder returns the passed http.Response unmodified. Responders may or may not be safe to share and re-used: It depends on the applied decorators. For example, a standard decorator that closes the response body is fine to share whereas a decorator that reads the body into a passed struct is not.
To prevent memory leaks, ensure that at least one Responder closes the response body.
func DecorateResponder(r Responder, decorators ...RespondDecorator) Responder
DecorateResponder accepts a Responder and a, possibly empty, set of RespondDecorators, which it applies to the Responder. Decorators are applied in the order received, but their affect upon the request depends on whether they are a pre-decorator (react to the http.Response and then pass it along) or a post-decorator (pass the http.Response along and then react).
ResponderFunc is a method that implements the Responder interface.
type ResponderFunc func(*http.Response) error
func (rf ResponderFunc) Respond(r *http.Response) error
Respond implements the Responder interface on ResponderFunc.
Response serves as the base for all responses from generated clients. It provides access to the last http.Response.
type Response struct {
*http.Response `json:"-"`
}
func (r Response) HasHTTPStatus(statusCodes ...int) bool
HasHTTPStatus returns true if the returned HTTP status code matches one of the provided status codes. If there was no response (i.e. the underlying http.Response is nil) or not status codes are provided the return value is false.
func (r Response) IsHTTPStatus(statusCode int) bool
IsHTTPStatus returns true if the returned HTTP status code matches the provided status code. If there was no response (i.e. the underlying http.Response is nil) the return value is false.
RetriableRequest provides facilities for retrying an HTTP request.
type RetriableRequest struct {
// contains filtered or unexported fields
}
func NewRetriableRequest(req *http.Request) *RetriableRequest
NewRetriableRequest returns a wrapper around an HTTP request that support retry logic.
func (rr *RetriableRequest) Prepare() (err error)
Prepare signals that the request is about to be sent.
func (rr *RetriableRequest) Request() *http.Request
Request returns the wrapped HTTP request.
SASTokenAuthorizer implements an authorization for SAS Token Authentication this can be used for interaction with Blob Storage Endpoints
type SASTokenAuthorizer struct {
// contains filtered or unexported fields
}
func NewSASTokenAuthorizer(sasToken string) (*SASTokenAuthorizer, error)
NewSASTokenAuthorizer creates a SASTokenAuthorizer using the given credentials
func (sas *SASTokenAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds a shared access signature token to the URI's query parameters. This can be used for the Blob, Queue, and File Services.
SendDecorator takes and possibly decorates, by wrapping, a Sender. Decorators may affect the http.Request and pass it along or, first, pass the http.Request along then react to the http.Response result.
type SendDecorator func(Sender) Sender
func AfterDelay(d time.Duration) SendDecorator
AfterDelay returns a SendDecorator that delays for the passed time.Duration before invoking the Sender. The delay may be terminated by closing the optional channel on the http.Request. If canceled, no further Senders are invoked.
func AsIs() SendDecorator
AsIs returns a SendDecorator that invokes the passed Sender without modifying the http.Request.
func DoCloseIfError() SendDecorator
DoCloseIfError returns a SendDecorator that first invokes the passed Sender after which it closes the response if the passed Sender returns an error and the response body exists.
func DoErrorIfStatusCode(codes ...int) SendDecorator
DoErrorIfStatusCode returns a SendDecorator that emits an error if the response StatusCode is among the set passed. Since these are artificial errors, the response body may still require closing.
▹ Example
func DoErrorUnlessStatusCode(codes ...int) SendDecorator
DoErrorUnlessStatusCode returns a SendDecorator that emits an error unless the response StatusCode is among the set passed. Since these are artificial errors, the response body may still require closing.
func DoPollForStatusCodes(duration time.Duration, delay time.Duration, codes ...int) SendDecorator
DoPollForStatusCodes returns a SendDecorator that polls if the http.Response contains one of the passed status codes. It expects the http.Response to contain a Location header providing the URL at which to poll (using GET) and will poll until the time passed is equal to or greater than the supplied duration. It will delay between requests for the duration specified in the RetryAfter header or, if the header is absent, the passed delay. Polling may be canceled by closing the optional channel on the http.Request.
func DoRetryForAttempts(attempts int, backoff time.Duration) SendDecorator
DoRetryForAttempts returns a SendDecorator that retries a failed request for up to the specified number of attempts, exponentially backing off between requests using the supplied backoff time.Duration (which may be zero). Retrying may be canceled by closing the optional channel on the http.Request.
▹ Example
func DoRetryForDuration(d time.Duration, backoff time.Duration) SendDecorator
DoRetryForDuration returns a SendDecorator that retries the request until the total time is equal to or greater than the specified duration, exponentially backing off between requests using the supplied backoff time.Duration (which may be zero). Retrying may be canceled by closing the optional channel on the http.Request.
func DoRetryForStatusCodes(attempts int, backoff time.Duration, codes ...int) SendDecorator
DoRetryForStatusCodes returns a SendDecorator that retries for specified statusCodes for up to the specified number of attempts, exponentially backing off between requests using the supplied backoff time.Duration (which may be zero). Retrying may be canceled by cancelling the context on the http.Request. NOTE: Code http.StatusTooManyRequests (429) will *not* be counted against the number of attempts.
func DoRetryForStatusCodesWithCap(attempts int, backoff, cap time.Duration, codes ...int) SendDecorator
DoRetryForStatusCodesWithCap returns a SendDecorator that retries for specified statusCodes for up to the specified number of attempts, exponentially backing off between requests using the supplied backoff time.Duration (which may be zero). To cap the maximum possible delay between iterations specify a value greater than zero for cap. Retrying may be canceled by cancelling the context on the http.Request.
func GetSendDecorators(ctx context.Context, defaultSendDecorators ...SendDecorator) []SendDecorator
GetSendDecorators returns the SendDecorators in the provided context or the provided default SendDecorators.
func WithLogging(logger *log.Logger) SendDecorator
WithLogging returns a SendDecorator that implements simple before and after logging of the request.
Sender is the interface that wraps the Do method to send HTTP requests.
The standard http.Client conforms to this interface.
type Sender interface {
Do(*http.Request) (*http.Response, error)
}
func CreateSender(decorators ...SendDecorator) Sender
CreateSender creates, decorates, and returns, as a Sender, the default http.Client.
func DecorateSender(s Sender, decorators ...SendDecorator) Sender
DecorateSender accepts a Sender and a, possibly empty, set of SendDecorators, which is applies to the Sender. Decorators are applied in the order received, but their affect upon the request depends on whether they are a pre-decorator (change the http.Request and then pass it along) or a post-decorator (pass the http.Request along and react to the results in http.Response).
SenderFunc is a method that implements the Sender interface.
type SenderFunc func(*http.Request) (*http.Response, error)
func (sf SenderFunc) Do(r *http.Request) (*http.Response, error)
Do implements the Sender interface on SenderFunc.
SharedKeyAuthorizer implements an authorization for Shared Key this can be used for interaction with Blob, File and Queue Storage Endpoints
type SharedKeyAuthorizer struct {
// contains filtered or unexported fields
}
func NewSharedKeyAuthorizer(accountName, accountKey string, keyType SharedKeyType) (*SharedKeyAuthorizer, error)
NewSharedKeyAuthorizer creates a SharedKeyAuthorizer using the provided credentials and shared key type.
func (sk *SharedKeyAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds an HTTP Authorization header whose value is "<SharedKeyType> " followed by the computed key. This can be used for the Blob, Queue, and File Services
from: https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key You may use Shared Key authorization to authorize a request made against the 2009-09-19 version and later of the Blob and Queue services, and version 2014-02-14 and later of the File services.
SharedKeyType defines the enumeration for the various shared key types. See https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key for details on the shared key types.
type SharedKeyType string
const (
// SharedKey is used to authorize against blobs, files and queues services.
SharedKeyType = "sharedKey"
// SharedKeyForTable is used to authorize against the table service.
SharedKeyType = "sharedKeyTable"
// SharedKeyLite is used to authorize against blobs, files and queues services. It's provided for
// backwards compatibility with API versions before 2009-09-19. Prefer SharedKey instead.
SharedKeyType = "sharedKeyLite"
// SharedKeyLiteForTable is used to authorize against the table service. It's provided for
// backwards compatibility with older table API versions. Prefer SharedKeyForTable instead.
SharedKeyType = "sharedKeyLiteTable"
)