Documentation ¶
Overview ¶
Package autorest implements an HTTP request pipeline suitable for use across multiple go-routines and provides the shared routines relied on by AutoRest (see https://github.com/Azure/autorest/) generated Go code.
The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending, and Responding. A typical pattern is:
req, err := Prepare(&http.Request{}, token.WithAuthorization()) resp, err := Send(req, WithLogging(logger), DoErrorIfStatusCode(http.StatusInternalServerError), DoCloseIfError(), DoRetryForAttempts(5, time.Second)) err = Respond(resp, ByDiscardingBody(), ByClosing())
Each phase relies on decorators to modify and / or manage processing. Decorators may first modify and then pass the data along, pass the data first and then modify the result, or wrap themselves around passing the data (such as a logger might do). Decorators run in the order provided. For example, the following:
req, err := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/"), WithPath("a"), WithPath("b"), WithPath("c"))
will set the URL to:
https://microsoft.com/a/b/c
Preparers and Responders may be shared and re-used (assuming the underlying decorators support sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders shared among multiple go-routines, and a single Sender shared among multiple sending go-routines, all bound together by means of input / output channels.
Decorators hold their passed state within a closure (such as the path components in the example above). Be careful to share Preparers and Responders only in a context where such held state applies. For example, it may not make sense to share a Preparer that applies a query string from a fixed set of values. Similarly, sharing a Responder that reads the response body into a passed struct (e.g., ByUnmarshallingJson) is likely incorrect.
Lastly, the Swagger specification (https://swagger.io) that drives AutoRest (https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct parsing and formatting.
Errors raised by autorest objects and methods will conform to the autorest.Error interface.
See the included examples for more detail. For details on the suggested use of this package by generated clients, see the Client described below.
Index ¶
- Constants
- Variables
- func AsStringSlice(s interface{}) ([]string, error)
- func ChangeToGet(req *http.Request) *http.Request
- func CopyAndDecode(encodedAs EncodedAs, r io.Reader, v interface{}) (bytes.Buffer, error)
- func DelayForBackoff(backoff time.Duration, attempt int, cancel <-chan struct{}) bool
- func DelayForBackoffWithCap(backoff, cap time.Duration, attempt int, cancel <-chan struct{}) bool
- func DelayWithRetryAfter(resp *http.Response, cancel <-chan struct{}) bool
- func DrainResponseBody(resp *http.Response) error
- func Encode(location string, v interface{}, sep ...string) string
- func ExtractHeader(header string, resp *http.Response) []string
- func ExtractHeaderValue(header string, resp *http.Response) string
- func GetLocation(resp *http.Response) string
- func GetRetryAfter(resp *http.Response, defaultDelay time.Duration) time.Duration
- func IsTemporaryNetworkError(err error) bool
- func IsTokenRefreshError(err error) bool
- func MapToValues(m map[string]interface{}) url.Values
- func NewPollingRequest(resp *http.Response, cancel <-chan struct{}) (*http.Request, error)
- func NewPollingRequestWithContext(ctx context.Context, resp *http.Response) (*http.Request, error)
- func Prepare(r *http.Request, decorators ...PrepareDecorator) (*http.Request, error)
- func Respond(r *http.Response, decorators ...RespondDecorator) error
- func ResponseHasStatusCode(resp *http.Response, codes ...int) bool
- func Send(r *http.Request, decorators ...SendDecorator) (*http.Response, error)
- func SendWithSender(s Sender, r *http.Request, decorators ...SendDecorator) (*http.Response, error)
- func String(v interface{}, sep ...string) string
- func TeeReadCloser(rc io.ReadCloser, w io.Writer) io.ReadCloser
- func UserAgent() string
- func Version() string
- func WithPrepareDecorators(ctx context.Context, prepareDecorator []PrepareDecorator) context.Context
- func WithSendDecorators(ctx context.Context, sendDecorator []SendDecorator) context.Context
- type APIKeyAuthorizer
- func NewAPIKeyAuthorizer(headers map[string]interface{}, queryParameters map[string]interface{}) *APIKeyAuthorizer
- func NewAPIKeyAuthorizerWithHeaders(headers map[string]interface{}) *APIKeyAuthorizer
- func NewAPIKeyAuthorizerWithQueryParameters(queryParameters map[string]interface{}) *APIKeyAuthorizer
- type Authorizer
- type BasicAuthorizer
- type BearerAuthorizer
- type BearerAuthorizerCallback
- type BearerAuthorizerCallbackFunc
- type Client
- func (c *Client) AddToUserAgent(extension string) error
- func (c Client) ByInspecting() RespondDecorator
- func (c Client) Do(r *http.Request) (*http.Response, error)
- func (c Client) Send(req *http.Request, decorators ...SendDecorator) (*http.Response, error)
- func (c Client) WithAuthorization() PrepareDecorator
- func (c Client) WithInspection() PrepareDecorator
- type ClientOptions
- type CognitiveServicesAuthorizer
- type Decoder
- type DetailedError
- func NewError(packageType string, method string, message string, args ...interface{}) DetailedError
- func NewErrorWithError(original error, packageType string, method string, resp *http.Response, ...) DetailedError
- func NewErrorWithResponse(packageType string, method string, resp *http.Response, message string, ...) DetailedError
- type EncodedAs
- type EventGridKeyAuthorizer
- type LoggingInspector
- type MultiTenantServicePrincipalTokenAuthorizer
- type NullAuthorizer
- type PrepareDecorator
- func AsContentType(contentType string) PrepareDecorator
- func AsDelete() PrepareDecorator
- func AsFormURLEncoded() PrepareDecorator
- func AsGet() PrepareDecorator
- func AsHead() PrepareDecorator
- func AsJSON() PrepareDecorator
- func AsMerge() PrepareDecorator
- func AsOctetStream() PrepareDecorator
- func AsOptions() PrepareDecorator
- func AsPatch() PrepareDecorator
- func AsPost() PrepareDecorator
- func AsPut() PrepareDecorator
- func GetPrepareDecorators(ctx context.Context, defaultPrepareDecorators ...PrepareDecorator) []PrepareDecorator
- func WithBaseURL(baseURL string) PrepareDecorator
- func WithBearerAuthorization(token string) PrepareDecorator
- func WithBool(v bool) PrepareDecorator
- func WithBytes(input *[]byte) PrepareDecorator
- func WithCustomBaseURL(baseURL string, urlParameters map[string]interface{}) PrepareDecorator
- func WithEscapedPathParameters(path string, pathParameters map[string]interface{}) PrepareDecorator
- func WithFile(f io.ReadCloser) PrepareDecorator
- func WithFloat32(v float32) PrepareDecorator
- func WithFloat64(v float64) PrepareDecorator
- func WithFormData(v url.Values) PrepareDecorator
- func WithHeader(header string, value string) PrepareDecorator
- func WithHeaders(headers map[string]interface{}) PrepareDecorator
- func WithInt32(v int32) PrepareDecorator
- func WithInt64(v int64) PrepareDecorator
- func WithJSON(v interface{}) PrepareDecorator
- func WithMethod(method string) PrepareDecorator
- func WithMultiPartFormData(formDataParameters map[string]interface{}) PrepareDecorator
- func WithNothing() PrepareDecorator
- func WithPath(path string) PrepareDecorator
- func WithPathParameters(path string, pathParameters map[string]interface{}) PrepareDecorator
- func WithQueryParameters(queryParameters map[string]interface{}) PrepareDecorator
- func WithString(v string) PrepareDecorator
- func WithUserAgent(ua string) PrepareDecorator
- func WithXML(v interface{}) PrepareDecorator
- type Preparer
- type PreparerFunc
- type RespondDecorator
- func ByClosing() RespondDecorator
- func ByClosingIfError() RespondDecorator
- func ByCopying(b *bytes.Buffer) RespondDecorator
- func ByDiscardingBody() RespondDecorator
- func ByIgnoring() RespondDecorator
- func ByUnmarshallingBytes(v *[]byte) RespondDecorator
- func ByUnmarshallingJSON(v interface{}) RespondDecorator
- func ByUnmarshallingXML(v interface{}) RespondDecorator
- func WithErrorUnlessOK() RespondDecorator
- func WithErrorUnlessStatusCode(codes ...int) RespondDecorator
- type Responder
- type ResponderFunc
- type Response
- type RetriableRequest
- type SASTokenAuthorizer
- type SendDecorator
- func AfterDelay(d time.Duration) SendDecorator
- func AsIs() SendDecorator
- func DoCloseIfError() SendDecorator
- func DoErrorIfStatusCode(codes ...int) SendDecorator
- func DoErrorUnlessStatusCode(codes ...int) SendDecorator
- func DoPollForStatusCodes(duration time.Duration, delay time.Duration, codes ...int) SendDecorator
- func DoRetryForAttempts(attempts int, backoff time.Duration) SendDecorator
- func DoRetryForDuration(d time.Duration, backoff time.Duration) SendDecorator
- func DoRetryForStatusCodes(attempts int, backoff time.Duration, codes ...int) SendDecorator
- func DoRetryForStatusCodesWithCap(attempts int, backoff, cap time.Duration, codes ...int) SendDecorator
- func GetSendDecorators(ctx context.Context, defaultSendDecorators ...SendDecorator) []SendDecorator
- func WithLogging(logger *log.Logger) SendDecorator
- type Sender
- type SenderFunc
- type SharedKeyAuthorizer
- type SharedKeyType
Examples ¶
- AsStringSlice
- ByUnmarshallingJSON
- ByUnmarshallingXML
- CreatePreparer
- CreatePreparer (Chain)
- CreatePreparer (Multiple)
- DoErrorIfStatusCode
- DoRetryForAttempts
- Prepare
- PrepareDecorator
- PrepareDecorator (Pre)
- SendWithSender
- String
- WithBaseURL
- WithCustomBaseURL
- WithErrorUnlessOK
- WithEscapedPathParameters
- WithFormData
- WithHeader
- WithJSON
- WithPathParameters
- WithQueryParameters
- WithXML
Constants ¶
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 = 60 * 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
)
Variables ¶
var Count429AsRetry = true
Count429AsRetry indicates that a 429 response should be included as a retry attempt.
var Max429Delay time.Duration
Max429Delay is the maximum duration to wait between retries on a 429 if no Retry-After header was received.
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, } )
Functions ¶
func AsStringSlice ¶
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 ¶
type TestEnumType string a := []TestEnumType{"value1", "value2"} b, _ := AsStringSlice(a) for _, c := range b { fmt.Println(c) }
Output: value1 value2
func ChangeToGet ¶
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 ¶
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 ¶
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 ¶ added in v0.4.0
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 ¶
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 ¶ added in v0.9.5
DrainResponseBody reads the response body then closes it.
func ExtractHeader ¶
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 ¶
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 ¶
GetLocation retrieves the URL from the Location header of the passed response.
func GetRetryAfter ¶
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 ¶
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 ¶
IsTokenRefreshError returns true if the specified error implements the TokenRefreshError interface. If err is a DetailedError it will walk the chain of Original errors.
func MapToValues ¶
MapToValues method converts map[string]interface{} to url.Values.
func NewPollingRequest ¶
NewPollingRequest allocates and returns a new http.Request to poll for the passed response.
func NewPollingRequestWithContext ¶
NewPollingRequestWithContext allocates and returns a new http.Request with the specified context to poll for the passed response.
func Prepare ¶
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 ¶
Create and prepare an http.Request in one call
r, err := Prepare(&http.Request{}, AsGet(), WithBaseURL("https://microsoft.com/"), WithPath("a/b/c/")) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Printf("%s %s", r.Method, r.URL) }
Output: GET https://microsoft.com/a/b/c/
func Respond ¶
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 ¶
ResponseHasStatusCode returns true if the status code in the HTTP Response is in the passed set and false otherwise.
func Send ¶
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 ¶
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 ¶
r := mocks.NewResponseWithStatus("202 Accepted", http.StatusAccepted) mocks.SetAcceptedHeaders(r) client := mocks.NewSender() client.AppendAndRepeatResponse(r, 10) logger := log.New(os.Stdout, "autorest: ", 0) na := NullAuthorizer{} req, _ := Prepare(&http.Request{}, AsGet(), WithBaseURL("https://microsoft.com/a/b/c/"), na.WithAuthorization()) r, _ = SendWithSender(client, req, WithLogging(logger), DoErrorIfStatusCode(http.StatusAccepted), DoCloseIfError(), DoRetryForAttempts(5, time.Duration(0))) Respond(r, ByDiscardingBody(), ByClosing())
Output: autorest: Sending GET https://microsoft.com/a/b/c/ autorest: GET https://microsoft.com/a/b/c/ received 202 Accepted autorest: Sending GET https://microsoft.com/a/b/c/ autorest: GET https://microsoft.com/a/b/c/ received 202 Accepted autorest: Sending GET https://microsoft.com/a/b/c/ autorest: GET https://microsoft.com/a/b/c/ received 202 Accepted autorest: Sending GET https://microsoft.com/a/b/c/ autorest: GET https://microsoft.com/a/b/c/ received 202 Accepted autorest: Sending GET https://microsoft.com/a/b/c/ autorest: GET https://microsoft.com/a/b/c/ received 202 Accepted
func 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 ¶
m := []string{ "string1", "string2", "string3", } fmt.Println(String(m, ","))
Output: string1,string2,string3
func TeeReadCloser ¶
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 ¶
func UserAgent() string
UserAgent returns a string containing the Go version, system architecture and OS, and the go-autorest version.
func WithPrepareDecorators ¶ added in v0.6.0
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 ¶ added in v0.4.0
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.
Types ¶
type APIKeyAuthorizer ¶
type APIKeyAuthorizer struct {
// contains filtered or unexported fields
}
APIKeyAuthorizer implements API Key authorization.
func NewAPIKeyAuthorizer ¶
func NewAPIKeyAuthorizer(headers map[string]interface{}, queryParameters map[string]interface{}) *APIKeyAuthorizer
NewAPIKeyAuthorizer creates an ApiKeyAuthorizer with headers.
func NewAPIKeyAuthorizerWithHeaders ¶
func NewAPIKeyAuthorizerWithHeaders(headers map[string]interface{}) *APIKeyAuthorizer
NewAPIKeyAuthorizerWithHeaders creates an ApiKeyAuthorizer with headers.
func NewAPIKeyAuthorizerWithQueryParameters ¶
func NewAPIKeyAuthorizerWithQueryParameters(queryParameters map[string]interface{}) *APIKeyAuthorizer
NewAPIKeyAuthorizerWithQueryParameters creates an ApiKeyAuthorizer with query parameters.
func (*APIKeyAuthorizer) WithAuthorization ¶
func (aka *APIKeyAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds an HTTP headers and Query Parameters.
type Authorizer ¶
type Authorizer interface {
WithAuthorization() PrepareDecorator
}
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 BasicAuthorizer ¶
type BasicAuthorizer struct {
// contains filtered or unexported fields
}
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.
func NewBasicAuthorizer ¶
func NewBasicAuthorizer(userName, password string) *BasicAuthorizer
NewBasicAuthorizer creates a new BasicAuthorizer with the specified username and password.
func (*BasicAuthorizer) WithAuthorization ¶
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.
type BearerAuthorizer ¶
type BearerAuthorizer struct {
// contains filtered or unexported fields
}
BearerAuthorizer implements the bearer authorization
func NewBearerAuthorizer ¶
func NewBearerAuthorizer(tp adal.OAuthTokenProvider) *BearerAuthorizer
NewBearerAuthorizer crates a BearerAuthorizer using the given token provider
func (*BearerAuthorizer) TokenProvider ¶ added in v0.11.0
func (ba *BearerAuthorizer) TokenProvider() adal.OAuthTokenProvider
TokenProvider returns OAuthTokenProvider so that it can be used for authorization outside the REST.
func (*BearerAuthorizer) WithAuthorization ¶
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.
type BearerAuthorizerCallback ¶
type BearerAuthorizerCallback struct {
// contains filtered or unexported fields
}
BearerAuthorizerCallback implements bearer authorization via a callback.
func NewBearerAuthorizerCallback ¶
func NewBearerAuthorizerCallback(s Sender, callback BearerAuthorizerCallbackFunc) *BearerAuthorizerCallback
NewBearerAuthorizerCallback creates a bearer authorization callback. The callback is invoked when the HTTP request is submitted.
func (*BearerAuthorizerCallback) WithAuthorization ¶
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.
type BearerAuthorizerCallbackFunc ¶
type BearerAuthorizerCallbackFunc func(tenantID, resource string) (*BearerAuthorizer, error)
BearerAuthorizerCallbackFunc is the authentication callback signature.
type Client ¶
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 default number of retry attempts for client. 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 }
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.
func NewClientWithOptions ¶
func NewClientWithOptions(options ClientOptions) Client
NewClientWithOptions returns an instance of a Client with the specified values.
func NewClientWithUserAgent ¶
NewClientWithUserAgent returns an instance of a Client with the UserAgent set to the passed string.
func (*Client) AddToUserAgent ¶
AddToUserAgent adds an extension to the current user agent
func (Client) ByInspecting ¶
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 (Client) Do ¶
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 (Client) Send ¶ added in v0.9.6
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 (Client) WithAuthorization ¶
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 (Client) WithInspection ¶
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.
type ClientOptions ¶
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 }
ClientOptions contains various Client configuration options.
type CognitiveServicesAuthorizer ¶
type CognitiveServicesAuthorizer struct {
// contains filtered or unexported fields
}
CognitiveServicesAuthorizer implements authorization for Cognitive Services.
func NewCognitiveServicesAuthorizer ¶
func NewCognitiveServicesAuthorizer(subscriptionKey string) *CognitiveServicesAuthorizer
NewCognitiveServicesAuthorizer is
func (*CognitiveServicesAuthorizer) WithAuthorization ¶
func (csa *CognitiveServicesAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization is
type Decoder ¶
type Decoder interface {
Decode(v interface{}) error
}
Decoder defines the decoding method json.Decoder and xml.Decoder share
type DetailedError ¶
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 }
DetailedError encloses a error with details of the package, method, and associated HTTP status code (if any).
func NewError ¶
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 ¶
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 ¶
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 (DetailedError) Error ¶
func (e DetailedError) Error() string
Error returns a formatted containing all available details (i.e., PackageType, Method, StatusCode, Message, and original error (if any)).
type EncodedAs ¶
type EncodedAs string
EncodedAs is a series of constants specifying various data encodings
type EventGridKeyAuthorizer ¶
type EventGridKeyAuthorizer struct {
// contains filtered or unexported fields
}
EventGridKeyAuthorizer implements authorization for event grid using key authentication.
func NewEventGridKeyAuthorizer ¶
func NewEventGridKeyAuthorizer(topicKey string) EventGridKeyAuthorizer
NewEventGridKeyAuthorizer creates a new EventGridKeyAuthorizer with the specified topic key.
func (EventGridKeyAuthorizer) WithAuthorization ¶
func (egta EventGridKeyAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that adds the aeg-sas-key authentication header.
type LoggingInspector ¶
LoggingInspector implements request and response inspectors that log the full request and response to a supplied log.
func (LoggingInspector) ByInspecting ¶
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 (LoggingInspector) WithInspection ¶
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.
type MultiTenantServicePrincipalTokenAuthorizer ¶ added in v0.4.0
type MultiTenantServicePrincipalTokenAuthorizer interface {
WithAuthorization() PrepareDecorator
}
MultiTenantServicePrincipalTokenAuthorizer provides authentication across tenants.
func NewMultiTenantServicePrincipalTokenAuthorizer ¶ added in v0.4.0
func NewMultiTenantServicePrincipalTokenAuthorizer(tp adal.MultitenantOAuthTokenProvider) MultiTenantServicePrincipalTokenAuthorizer
NewMultiTenantServicePrincipalTokenAuthorizer crates a BearerAuthorizer using the given token provider
type NullAuthorizer ¶
type NullAuthorizer struct{}
NullAuthorizer implements a default, "do nothing" Authorizer.
func (NullAuthorizer) WithAuthorization ¶
func (na NullAuthorizer) WithAuthorization() PrepareDecorator
WithAuthorization returns a PrepareDecorator that does nothing.
type PrepareDecorator ¶
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.
Example ¶
PrepareDecorators wrap and invoke a Preparer. Most often, the decorator invokes the passed Preparer and decorates the response.
path := "a/b/c/" pd := func() PrepareDecorator { return func(p Preparer) Preparer { return PreparerFunc(func(r *http.Request) (*http.Request, error) { r, err := p.Prepare(r) if err == nil { if r.URL == nil { return r, fmt.Errorf("ERROR: URL is not set") } r.URL.Path += path } return r, err }) } } r, _ := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/"), pd()) fmt.Printf("Path is %s\n", r.URL)
Output: Path is https://microsoft.com/a/b/c/
Example (Pre) ¶
PrepareDecorators may also modify and then invoke the Preparer.
pd := func() PrepareDecorator { return func(p Preparer) Preparer { return PreparerFunc(func(r *http.Request) (*http.Request, error) { r.Header.Add(http.CanonicalHeaderKey("ContentType"), "application/json") return p.Prepare(r) }) } } r, _ := Prepare(&http.Request{Header: http.Header{}}, pd()) fmt.Printf("ContentType is %s\n", r.Header.Get("ContentType"))
Output: ContentType is application/json
func AsContentType ¶
func AsContentType(contentType string) PrepareDecorator
AsContentType returns a PrepareDecorator that adds an HTTP Content-Type header whose value is the passed contentType.
func AsDelete ¶
func AsDelete() PrepareDecorator
AsDelete returns a PrepareDecorator that sets the HTTP method to DELETE.
func AsFormURLEncoded ¶
func AsFormURLEncoded() PrepareDecorator
AsFormURLEncoded returns a PrepareDecorator that adds an HTTP Content-Type header whose value is "application/x-www-form-urlencoded".
func AsGet ¶
func AsGet() PrepareDecorator
AsGet returns a PrepareDecorator that sets the HTTP method to GET.
func AsHead ¶
func AsHead() PrepareDecorator
AsHead returns a PrepareDecorator that sets the HTTP method to HEAD.
func AsJSON ¶
func AsJSON() PrepareDecorator
AsJSON returns a PrepareDecorator that adds an HTTP Content-Type header whose value is "application/json".
func AsMerge ¶ added in v0.3.0
func AsMerge() PrepareDecorator
AsMerge returns a PrepareDecorator that sets the HTTP method to MERGE.
func AsOctetStream ¶
func AsOctetStream() PrepareDecorator
AsOctetStream returns a PrepareDecorator that adds the "application/octet-stream" Content-Type header.
func AsOptions ¶
func AsOptions() PrepareDecorator
AsOptions returns a PrepareDecorator that sets the HTTP method to OPTIONS.
func AsPatch ¶
func AsPatch() PrepareDecorator
AsPatch returns a PrepareDecorator that sets the HTTP method to PATCH.
func AsPost ¶
func AsPost() PrepareDecorator
AsPost returns a PrepareDecorator that sets the HTTP method to POST.
func AsPut ¶
func AsPut() PrepareDecorator
AsPut returns a PrepareDecorator that sets the HTTP method to PUT.
func GetPrepareDecorators ¶ added in v0.6.0
func GetPrepareDecorators(ctx context.Context, defaultPrepareDecorators ...PrepareDecorator) []PrepareDecorator
GetPrepareDecorators returns the PrepareDecorators in the provided context or the provided default PrepareDecorators.
func WithBaseURL ¶
func WithBaseURL(baseURL string) PrepareDecorator
WithBaseURL returns a PrepareDecorator that populates the http.Request with a url.URL constructed from the supplied baseUrl.
Example ¶
Create a request for a supplied base URL and path
r, err := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/a/b/c/")) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://microsoft.com/a/b/c/
func WithBearerAuthorization ¶
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 ¶
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 ¶ added in v0.3.0
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 ¶
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 ¶
r, err := Prepare(&http.Request{}, WithCustomBaseURL("https://{account}.{service}.core.windows.net/", map[string]interface{}{ "account": "myaccount", "service": "blob", })) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://myaccount.blob.core.windows.net/
func WithEscapedPathParameters ¶
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 ¶
Create a request from a path with escaped parameters
params := map[string]interface{}{ "param1": "a b c", "param2": "d e f", } r, err := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/"), WithEscapedPathParameters("/{param1}/b/{param2}/", params)) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://microsoft.com/a+b+c/b/d+e+f/
func WithFile ¶
func WithFile(f io.ReadCloser) PrepareDecorator
WithFile returns a PrepareDecorator that sends file in request body.
func WithFloat32 ¶
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 ¶
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 ¶
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 ¶
Create a request whose Body is the JSON encoding of a structure
v := url.Values{} v.Add("name", "Rob Pike") v.Add("age", "42") r, err := Prepare(&http.Request{}, WithFormData(v)) if err != nil { fmt.Printf("ERROR: %v\n", err) } b, err := ioutil.ReadAll(r.Body) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Printf("Request Body contains %s\n", string(b)) }
Output: Request Body contains age=42&name=Rob+Pike
func WithHeader ¶
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 ¶
Create a request with a custom HTTP header
r, err := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/a/b/c/"), WithHeader("x-foo", "bar")) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Printf("Header %s=%s\n", "x-foo", r.Header.Get("x-foo")) }
Output: Header x-foo=bar
func WithHeaders ¶
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 ¶
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 ¶
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 ¶
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 ¶
Create a request whose Body is the JSON encoding of a structure
t := mocks.T{Name: "Rob Pike", Age: 42} r, err := Prepare(&http.Request{}, WithJSON(&t)) if err != nil { fmt.Printf("ERROR: %v\n", err) } b, err := ioutil.ReadAll(r.Body) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Printf("Request Body contains %s\n", string(b)) }
Output: Request Body contains {"name":"Rob Pike","age":42}
func WithMethod ¶
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 ¶
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 ¶
func WithNothing() PrepareDecorator
WithNothing returns a "do nothing" PrepareDecorator that makes no changes to the passed http.Request.
func WithPath ¶
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 ¶
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 ¶
Create a request from a path with parameters
params := map[string]interface{}{ "param1": "a", "param2": "c", } r, err := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/"), WithPathParameters("/{param1}/b/{param2}/", params)) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://microsoft.com/a/b/c/
func WithQueryParameters ¶
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 ¶
Create a request with query parameters
params := map[string]interface{}{ "q1": []string{"value1"}, "q2": []string{"value2"}, } r, err := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/"), WithPath("/a/b/c/"), WithQueryParameters(params)) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://microsoft.com/a/b/c/?q1=value1&q2=value2
func WithString ¶
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 ¶
func WithUserAgent(ua string) PrepareDecorator
WithUserAgent returns a PrepareDecorator that adds an HTTP User-Agent header whose value is the passed string.
func WithXML ¶ added in v0.3.0
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 ¶
Create a request whose Body is the XML encoding of a structure
t := mocks.T{Name: "Rob Pike", Age: 42} r, err := Prepare(&http.Request{}, WithXML(&t)) if err != nil { fmt.Printf("ERROR: %v\n", err) } b, err := ioutil.ReadAll(r.Body) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Printf("Request Body contains %s\n", string(b)) }
Output: Request Body contains <?xml version="1.0" encoding="UTF-8"?> <T><Name>Rob Pike</Name><Age>42</Age></T>
type Preparer ¶
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.
func CreatePreparer ¶
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 ¶
Create a sequence of three Preparers that build up the URL path.
p := CreatePreparer( WithBaseURL("https://microsoft.com/"), WithPath("a"), WithPath("b"), WithPath("c")) r, err := p.Prepare(&http.Request{}) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://microsoft.com/a/b/c
Example (Chain) ¶
Create and chain separate Preparers
params := map[string]interface{}{ "param1": "a", "param2": "c", } p := CreatePreparer(WithBaseURL("https://microsoft.com/")) p = DecoratePreparer(p, WithPathParameters("/{param1}/b/{param2}/", params)) r, err := p.Prepare(&http.Request{}) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://microsoft.com/a/b/c/
Example (Multiple) ¶
Create and apply separate Preparers
params := map[string]interface{}{ "param1": "a", "param2": "c", } p1 := CreatePreparer(WithBaseURL("https://microsoft.com/")) p2 := CreatePreparer(WithPathParameters("/{param1}/b/{param2}/", params)) r, err := p1.Prepare(&http.Request{}) if err != nil { fmt.Printf("ERROR: %v\n", err) } r, err = p2.Prepare(r) if err != nil { fmt.Printf("ERROR: %v\n", err) } else { fmt.Println(r.URL) }
Output: https://microsoft.com/a/b/c/
func DecoratePreparer ¶
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).
type PreparerFunc ¶
PreparerFunc is a method that implements the Preparer interface.
type RespondDecorator ¶
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.
func ByClosing ¶
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 ¶
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 ¶
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 ¶
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 ¶
func ByIgnoring() RespondDecorator
ByIgnoring returns a RespondDecorator that ignores the passed http.Response passing it unexamined to the next RespondDecorator.
func ByUnmarshallingBytes ¶ added in v0.3.0
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 ¶
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 ¶
c := ` { "name" : "Rob Pike", "age" : 42 } ` type V struct { Name string `json:"name"` Age int `json:"age"` } v := &V{} Respond(mocks.NewResponseWithContent(c), ByUnmarshallingJSON(v), ByClosing()) fmt.Printf("%s is %d years old\n", v.Name, v.Age)
Output: Rob Pike is 42 years old
func ByUnmarshallingXML ¶
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 ¶
c := `<?xml version="1.0" encoding="UTF-8"?> <Person> <Name>Rob Pike</Name> <Age>42</Age> </Person>` type V struct { Name string `xml:"Name"` Age int `xml:"Age"` } v := &V{} Respond(mocks.NewResponseWithContent(c), ByUnmarshallingXML(v), ByClosing()) fmt.Printf("%s is %d years old\n", v.Name, v.Age)
Output: Rob Pike is 42 years old
func WithErrorUnlessOK ¶
func WithErrorUnlessOK() RespondDecorator
WithErrorUnlessOK returns a RespondDecorator that emits an error if the response StatusCode is anything other than HTTP 200.
Example ¶
r := mocks.NewResponse() r.Request = mocks.NewRequest() // Respond and leave the response body open (for a subsequent responder to close) err := Respond(r, WithErrorUnlessOK(), ByDiscardingBody(), ByClosingIfError()) if err == nil { fmt.Printf("%s of %s returned HTTP 200", r.Request.Method, r.Request.URL) // Complete handling the response and close the body Respond(r, ByDiscardingBody(), ByClosing()) }
Output: GET of https://microsoft.com/a/b/c/ returned HTTP 200
func WithErrorUnlessStatusCode ¶
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.
type Responder ¶
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.
func CreateResponder ¶
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 ¶
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).
type ResponderFunc ¶
ResponderFunc is a method that implements the Responder interface.
type Response ¶
Response serves as the base for all responses from generated clients. It provides access to the last http.Response.
func (Response) HasHTTPStatus ¶ added in v0.3.0
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 (Response) IsHTTPStatus ¶ added in v0.3.0
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.
type RetriableRequest ¶
type RetriableRequest struct {
// contains filtered or unexported fields
}
RetriableRequest provides facilities for retrying an HTTP request.
func NewRetriableRequest ¶
func NewRetriableRequest(req *http.Request) *RetriableRequest
NewRetriableRequest returns a wrapper around an HTTP request that support retry logic.
func (*RetriableRequest) Prepare ¶
func (rr *RetriableRequest) Prepare() (err error)
Prepare signals that the request is about to be sent.
func (*RetriableRequest) Request ¶
func (rr *RetriableRequest) Request() *http.Request
Request returns the wrapped HTTP request.
type SASTokenAuthorizer ¶ added in v0.9.3
type SASTokenAuthorizer struct {
// contains filtered or unexported fields
}
SASTokenAuthorizer implements an authorization for SAS Token Authentication this can be used for interaction with Blob Storage Endpoints
func NewSASTokenAuthorizer ¶ added in v0.9.3
func NewSASTokenAuthorizer(sasToken string) (*SASTokenAuthorizer, error)
NewSASTokenAuthorizer creates a SASTokenAuthorizer using the given credentials
func (*SASTokenAuthorizer) WithAuthorization ¶ added in v0.9.3
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.
type SendDecorator ¶
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.
func AfterDelay ¶
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 ¶
func AsIs() SendDecorator
AsIs returns a SendDecorator that invokes the passed Sender without modifying the http.Request.
func DoCloseIfError ¶
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 ¶
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 ¶
client := mocks.NewSender() client.AppendAndRepeatResponse(mocks.NewResponseWithStatus("204 NoContent", http.StatusNoContent), 10) // Chain decorators to retry the request, up to five times, if the status code is 204 r, _ := SendWithSender(client, mocks.NewRequest(), DoErrorIfStatusCode(http.StatusNoContent), DoCloseIfError(), DoRetryForAttempts(5, time.Duration(0))) Respond(r, ByDiscardingBody(), ByClosing()) fmt.Printf("Retry stopped after %d attempts with code %s", client.Attempts(), r.Status)
Output: Retry stopped after 5 attempts with code 204 NoContent
func DoErrorUnlessStatusCode ¶
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 ¶
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 ¶
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 ¶
client := mocks.NewSender() client.SetAndRepeatError(fmt.Errorf("Faux Error"), 10) // Retry with backoff -- ensure returned Bodies are closed r, _ := SendWithSender(client, mocks.NewRequest(), DoCloseIfError(), DoRetryForAttempts(5, time.Duration(0))) Respond(r, ByDiscardingBody(), ByClosing()) fmt.Printf("Retry stopped after %d attempts", client.Attempts())
Output: Retry stopped after 5 attempts
func DoRetryForDuration ¶
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 ¶
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 ¶ added in v0.4.0
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 ¶ added in v0.4.0
func GetSendDecorators(ctx context.Context, defaultSendDecorators ...SendDecorator) []SendDecorator
GetSendDecorators returns the SendDecorators in the provided context or the provided default SendDecorators.
func WithLogging ¶
func WithLogging(logger *log.Logger) SendDecorator
WithLogging returns a SendDecorator that implements simple before and after logging of the request.
type Sender ¶
Sender is the interface that wraps the Do method to send HTTP requests.
The standard http.Client conforms to this interface.
func CreateSender ¶
func CreateSender(decorators ...SendDecorator) Sender
CreateSender creates, decorates, and returns, as a Sender, the default http.Client.
func DecorateSender ¶
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).
type SenderFunc ¶
SenderFunc is a method that implements the Sender interface.
type SharedKeyAuthorizer ¶ added in v0.9.3
type SharedKeyAuthorizer struct {
// contains filtered or unexported fields
}
SharedKeyAuthorizer implements an authorization for Shared Key this can be used for interaction with Blob, File and Queue Storage Endpoints
func NewSharedKeyAuthorizer ¶ added in v0.9.3
func NewSharedKeyAuthorizer(accountName, accountKey string, keyType SharedKeyType) (*SharedKeyAuthorizer, error)
NewSharedKeyAuthorizer creates a SharedKeyAuthorizer using the provided credentials and shared key type.
func (*SharedKeyAuthorizer) WithAuthorization ¶ added in v0.9.3
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.
type SharedKeyType ¶ added in v0.9.3
type SharedKeyType string
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.
const ( SharedKeyType = "sharedKey" SharedKeyForTable SharedKeyType = "sharedKeyTable" // backwards compatibility with API versions before 2009-09-19. Prefer SharedKey instead. SharedKeyLite SharedKeyType = "sharedKeyLite" // backwards compatibility with older table API versions. Prefer SharedKeyForTable instead. SharedKeyLiteForTable SharedKeyType = "sharedKeyLiteTable" )SharedKey