azcore – github.com/Azure/azure-sdk-for-go/sdk/azcore Index | Examples | Files | Directories

package azcore

import "github.com/Azure/azure-sdk-for-go/sdk/azcore"

Package azcore implements an HTTP request/response middleware pipeline.

The middleware consists of three components.

Implementing the Policy Interface

A Policy can be implemented in two ways; as a first-class function for a stateless Policy, or as a method on a type for a stateful Policy. Note that HTTP requests made via the same pipeline share the same Policy instances, so if a Policy mutates its state it MUST be properly synchronized to avoid race conditions.

A Policy's Do method is called when an HTTP request wants to be sent over the network. The Do method can perform any operation(s) it desires. For example, it can log the outgoing request, mutate the URL, headers, and/or query parameters, inject a failure, etc. Once the Policy has successfully completed its request work, it must call the Next() method on the *azcore.Request instance in order to pass the request to the next Policy in the chain.

When an HTTP response comes back, the Policy then gets a chance to process the response/error. The Policy instance can log the response, retry the operation if it failed due to a transient error or timeout, unmarshal the response body, etc. Once the Policy has successfully completed its response work, it must return the *azcore.Response and error instances to its caller.

Template for implementing a stateless Policy: 

func NewMyStatelessPolicy() Policy {
   return azcore.PolicyFunc(func(req *azcore.Request) (*azcore.Response, error) {
      // TODO: mutate/process Request here

      // forward Request to next Policy & get Response/error
      resp, err := req.Next()

      // TODO: mutate/process Response/error here

      // return Response/error to previous Policy
      return resp, err
   })
}

Template for implementing a stateful Policy: 

type MyStatefulPolicy struct {
   // TODO: add configuration/setting fields here
}

// TODO: add initialization args to NewMyStatefulPolicy()
func NewMyStatefulPolicy() Policy {
   return &MyStatefulPolicy{
      // TODO: initialize configuration/setting fields here
   }
}

func (p *MyStatefulPolicy) Do(req *azcore.Request) (resp *azcore.Response, err error) {
      // TODO: mutate/process Request here

      // forward Request to next Policy & get Response/error
      resp, err := req.Next()

      // TODO: mutate/process Response/error here

      // return Response/error to previous Policy
      return resp, err
}

Implementing the Transport Interface

The Transport interface is responsible for sending the HTTP request and returning the corresponding HTTP response or error. The Transport is invoked by the last Policy in the chain. The default Transport implementation uses a shared http.Client from the standard library.

The same stateful/stateless rules for Policy implementations apply to Transport implementations.

Using Policy and Transport Instances Via a Pipeline

To use the Policy and Transport instances, an application passes them to the NewPipeline function. 

func NewPipeline(transport Transport, policies ...Policy) Pipeline

The specified Policy instances form a chain and are invoked in the order provided to NewPipeline followed by the Transport.

Once the Pipeline has been created, create a Request instance and pass it to Pipeline's Do method. 

func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*Request, error)

func (p Pipeline) Do(req *Request) (*Response, error)

The Pipeline.Do method sends the specified Request through the chain of Policy and Transport instances. The response/error is then sent through the same chain of Policy instances in reverse order. For example, assuming there are Policy types PolicyA, PolicyB, and PolicyC along with TransportA. 

pipeline := NewPipeline(TransportA, PolicyA, PolicyB, PolicyC)

The flow of Request and Response looks like the following: 

azcore.Request -> PolicyA -> PolicyB -> PolicyC -> TransportA -----+
                                                                   |
                                                            HTTP(s) endpoint
                                                                   |
caller <--------- PolicyA <- PolicyB <- PolicyC <- azcore.Response-+

Creating a Request Instance

The Request instance passed to Pipeline's Do method is a wrapper around an *http.Request. It also contains some internal state and provides various convenience methods. You create a Request instance by calling the NewRequest function: 

func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*Request, error)

If the Request should contain a body, call the SetBody method. 

func (req *Request) SetBody(body ReadSeekCloser, contentType string) error

A seekable stream is required so that upon retry, the retry Policy instance can seek the stream back to the beginning before retrying the network request and re-uploading the body.

Sending an Explicit Null

Operations like JSON-MERGE-PATCH send a JSON null to indicate a value should be deleted. 

{
   "delete-me": null
}

This requirement conflicts with the SDK's default marshalling that specifies "omitempty" as a means to resolve the ambiguity between a field to be excluded and its zero-value. 

type Widget struct {
   Name  *string `json:",omitempty"`
   Count *int    `json:",omitempty"`
}

In the above example, Name and Count are defined as pointer-to-type to disambiguate between a missing value (nil) and a zero-value (0) which might have semantic differences.

In a PATCH operation, any fields left as `nil` are to have their values preserved. When updating a Widget's count, one simply specifies the new value for Count, leaving Name nil.

To fulfill the requirement for sending a JSON null, the NullValue() function can be used. 

w := Widget{
   Count: azcore.NullValue(0).(*int),
}

This sends an explict "null" for Count, indicating that any current value for Count should be deleted.

Processing the Response

When the HTTP response is received, the underlying *http.Response is wrapped in a Response type. The Response type contains various convenience methods, like testing the HTTP response code and unmarshalling the response body in a particular format.

The Response is returned through all the Policy instances. Each Policy instance can inspect/mutate the embedded *http.Response.

Index

Examples

Constants 

const (
	// UserAgent is the string to be used in the user agent string when making requests.
	UserAgent = "azcore/" + Version

	// Version is the semantic version (see http://semver.org) of this module.
	Version = "v0.18.0"
)

Variables 

var (
	// StackFrameCount contains the number of stack frames to include when a trace is being collected.
	StackFrameCount = 32
)

Functions

func DecodeByteArray 

func DecodeByteArray(s string, v *[]byte, format Base64Encoding) error

DecodeByteArray will base-64 decode the provided string into v.

func Drain 

func Drain(resp *http.Response)

Drain reads the response body to completion then closes it. The bytes read are discarded.

func EncodeByteArray 

func EncodeByteArray(v []byte, format Base64Encoding) string

EncodeByteArray will base-64 encode the byte slice v.

func HasStatusCode 

func HasStatusCode(resp *http.Response, statusCodes ...int) bool

HasStatusCode returns true if the Response's status code is one of the specified values.

func IsNullValue 

func IsNullValue(v interface{}) bool

IsNullValue returns true if the field contains a null sentinel value. This is used by custom marshallers to properly encode a null value.

func JoinPaths 

func JoinPaths(root string, paths ...string) string

JoinPaths concatenates multiple URL path segments into one path, inserting path separation characters as required. JoinPaths will preserve query parameters in the root path

func NewResponseError 

func NewResponseError(inner error, resp *http.Response) error

NewResponseError wraps the specified error with an error that provides access to an HTTP response. If an HTTP request returns a non-successful status code, wrap the response and the associated error in this error type so that callers can access the underlying *http.Response as required. DO NOT wrap failed HTTP requests that returned an error and no response with this type.

func NewResponseProgress 

func NewResponseProgress(body io.ReadCloser, pr func(bytesTransferred int64)) io.ReadCloser

NewResponseProgress adds progress reporting to an HTTP response's body stream.

func NullValue 

func NullValue(v interface{}) interface{}

NullValue is used to send an explicit 'null' within a request. This is typically used in JSON-MERGE-PATCH operations to delete a value.

Example

Code:play  

package main

import (
	"encoding/json"
	"fmt"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
)

type Widget struct {
	Name  *string `json:",omitempty"`
	Count *int    `json:",omitempty"`
}

func (w Widget) MarshalJSON() ([]byte, error) {
	msg := map[string]interface{}{}
	if azcore.IsNullValue(w.Name) {
		msg["name"] = nil
	} else if w.Name != nil {
		msg["name"] = w.Name
	}
	if azcore.IsNullValue(w.Count) {
		msg["count"] = nil
	} else if w.Count != nil {
		msg["count"] = w.Count
	}
	return json.Marshal(msg)
}

func main() {
	w := Widget{
		Count: azcore.NullValue(0).(*int),
	}
	b, _ := json.Marshal(w)
	fmt.Println(string(b))
}

Output:

{"count":null}

func Payload 

func Payload(resp *http.Response) ([]byte, error)

Payload reads and returns the response body or an error. On a successful read, the response body is cached.

func RetryAfter 

func RetryAfter(resp *http.Response) time.Duration

RetryAfter returns non-zero if the response contains a Retry-After header value.

func UnmarshalAsByteArray 

func UnmarshalAsByteArray(resp *http.Response, v *[]byte, format Base64Encoding) error

UnmarshalAsByteArray will base-64 decode the received payload and place the result into the value pointed to by v.

func UnmarshalAsJSON 

func UnmarshalAsJSON(resp *http.Response, v interface{}) error

UnmarshalAsJSON calls json.Unmarshal() to unmarshal the received payload into the value pointed to by v.

func UnmarshalAsXML 

func UnmarshalAsXML(resp *http.Response, v interface{}) error

UnmarshalAsXML calls xml.Unmarshal() to unmarshal the received payload into the value pointed to by v.

func WithHTTPHeader 

func WithHTTPHeader(parent context.Context, header http.Header) context.Context

WithHTTPHeader adds the specified http.Header to the parent context. Use this to specify custom HTTP headers at the API-call level. Any overlapping headers will have their values replaced with the values specified here.

func WithRetryOptions 

func WithRetryOptions(parent context.Context, options RetryOptions) context.Context

WithRetryOptions adds the specified RetryOptions to the parent context. Use this to specify custom RetryOptions at the API-call level.

Types

type AccessToken 

type AccessToken struct {
	Token     string
	ExpiresOn time.Time
}

AccessToken represents an Azure service bearer access token with expiry information.

type AuthenticationOptions 

type AuthenticationOptions struct {
	// TokenRequest is a TokenRequestOptions that includes a scopes field which contains
	// the list of OAuth2 authentication scopes used when requesting a token.
	// This field is ignored for other forms of authentication (e.g. shared key).
	TokenRequest TokenRequestOptions
	// AuxiliaryTenants contains a list of additional tenant IDs to be used to authenticate
	// in cross-tenant applications.
	AuxiliaryTenants []string
}

AuthenticationOptions contains various options used to create a credential policy.

type Base64Encoding 

type Base64Encoding int

Base64Encoding is usesd to specify which base-64 encoder/decoder to use when encoding/decoding a slice of bytes to/from a string. 

const (
	// Base64StdFormat uses base64.StdEncoding for encoding and decoding payloads.
	Base64StdFormat Base64Encoding = 0

	// Base64URLFormat uses base64.RawURLEncoding for encoding and decoding payloads.
	Base64URLFormat Base64Encoding = 1
)

type Credential 

type Credential interface {
	// AuthenticationPolicy returns a policy that requests the credential and applies it to the HTTP request.
	NewAuthenticationPolicy(options AuthenticationOptions) Policy
}

Credential represents any credential type.

func NewAnonymousCredential 

func NewAnonymousCredential() Credential

NewAnonymousCredential is for use with HTTP(S) requests that read public resource or for use with Shared Access Signatures (SAS).

type ETag 

type ETag string

ETag is a property used for optimistic concurrency during updates ETag is a validator based on https://tools.ietf.org/html/rfc7232#section-2.3.2 An ETag can be empty (""). 

const ETagAny ETag = "*"

ETagAny is an ETag that represents everything, the value is "*"

func (ETag) Equals 

func (e ETag) Equals(other ETag) bool

Equals does a strong comparison of two ETags. Equals returns true when both ETags are not weak and the values of the underlying strings are equal.

func (ETag) IsWeak 

func (e ETag) IsWeak() bool

IsWeak specifies whether the ETag is strong or weak.

func (ETag) WeakEquals 

func (e ETag) WeakEquals(other ETag) bool

WeakEquals does a weak comparison of two ETags. Two ETags are equivalent if their opaque-tags match character-by-character, regardless of either or both being tagged as "weak".

type HTTPResponse 

type HTTPResponse interface {
	RawResponse() *http.Response
}

HTTPResponse provides access to an HTTP response when available. Errors returned from failed API calls will implement this interface. Use errors.As() to access this interface in the error chain. If there was no HTTP response then this interface will be omitted from any error in the chain.

type LogOptions 

type LogOptions struct {
	// IncludeBody indicates if request and response bodies should be included in logging.
	// The default value is false.
	// NOTE: enabling this can lead to disclosure of sensitive information, use with care.
	IncludeBody bool
}

LogOptions configures the logging policy's behavior.

type NonRetriableError 

type NonRetriableError interface {
	error
	NonRetriable()
}

NonRetriableError represents a non-transient error. This works in conjunction with the retry policy, indicating that the error condition is idempotent, so no retries will be attempted. Use errors.As() to access this interface in the error chain.

type Pipeline 

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

Pipeline represents a primitive for sending HTTP requests and receiving responses. Its behavior can be extended by specifying policies during construction.

func NewPipeline 

func NewPipeline(transport Transporter, policies ...Policy) Pipeline

NewPipeline creates a new Pipeline object from the specified Transport and Policies. If no transport is provided then the default *http.Client transport will be used.

func (Pipeline) Do 

func (p Pipeline) Do(req *Request) (*http.Response, error)

Do is called for each and every HTTP request. It passes the request through all the Policy objects (which can transform the Request's URL/query parameters/headers) and ultimately sends the transformed HTTP request over the network.

Example

Code:play  

package main

import (
	"context"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
)

func main() {
	req, err := azcore.NewRequest(context.Background(), http.MethodGet, "https://github.com/robots.txt")
	if err != nil {
		log.Fatal(err)
	}
	pipeline := azcore.NewPipeline(nil)
	resp, err := pipeline.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	robots, err := ioutil.ReadAll(resp.Body)
	resp.Body.Close()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s", robots)
}

type Policy 

type Policy interface {
	// Do applies the policy to the specified Request.  When implementing a Policy, mutate the
	// request before calling req.Next() to move on to the next policy, and respond to the result
	// before returning to the caller.
	Do(req *Request) (*http.Response, error)
}

Policy represents an extensibility point for the Pipeline that can mutate the specified Request and react to the received Response.

func NewLogPolicy 

func NewLogPolicy(o *LogOptions) Policy

NewLogPolicy creates a RequestLogPolicy object configured using the specified options. Pass nil to accept the default values; this is the same as passing a zero-value options.

func NewRetryPolicy 

func NewRetryPolicy(o *RetryOptions) Policy

NewRetryPolicy creates a policy object configured using the specified options. Pass nil to accept the default values; this is the same as passing a zero-value options.

func NewTelemetryPolicy 

func NewTelemetryPolicy(o *TelemetryOptions) Policy

NewTelemetryPolicy creates a telemetry policy object that adds telemetry information to outgoing HTTP requests. The format is [<application_id> ]azsdk-<sdk_language>-<package_name>/<package_version> <platform_info> [<custom>]. Pass nil to accept the default values; this is the same as passing a zero-value options.

type Poller 

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

Poller encapsulates state and logic for polling on long-running operations. NOTE: this is only meant for internal use in generated code.

func NewPoller 

func NewPoller(pollerID string, resp *http.Response, pl Pipeline, eu func(*http.Response) error) (*Poller, error)

NewPoller creates a Poller based on the provided initial response. pollerID - a unique identifier for an LRO, it's usually the client.Method string. NOTE: this is only meant for internal use in generated code.

func NewPollerFromResumeToken 

func NewPollerFromResumeToken(pollerID string, token string, pl Pipeline, eu func(*http.Response) error) (*Poller, error)

NewPollerFromResumeToken creates a Poller from a resume token string. pollerID - a unique identifier for an LRO, it's usually the client.Method string. NOTE: this is only meant for internal use in generated code.

func (*Poller) Done 

func (l *Poller) Done() bool

Done returns true if the LRO has reached a terminal state.

func (*Poller) FinalResponse 

func (l *Poller) FinalResponse(ctx context.Context, respType interface{}) (*http.Response, error)

FinalResponse will perform a final GET request and return the final HTTP response for the polling operation and unmarshall the content of the payload into the respType interface that is provided.

func (*Poller) Poll 

func (l *Poller) Poll(ctx context.Context) (*http.Response, error)

Poll sends a polling request to the polling endpoint and returns the response or error.

func (*Poller) PollUntilDone 

func (l *Poller) PollUntilDone(ctx context.Context, freq time.Duration, respType interface{}) (*http.Response, error)

PollUntilDone will handle the entire span of the polling operation until a terminal state is reached, then return the final HTTP response for the polling operation and unmarshal the content of the payload into the respType interface that is provided.

func (*Poller) ResumeToken 

func (l *Poller) ResumeToken() (string, error)

ResumeToken returns a token string that can be used to resume a poller that has not yet reached a terminal state.

type ReadSeekCloser 

type ReadSeekCloser interface {
	io.ReadCloser
	io.Seeker
}

ReadSeekCloser is the interface that groups the io.ReadCloser and io.Seeker interfaces.

func NewRequestProgress 

func NewRequestProgress(body ReadSeekCloser, pr func(bytesTransferred int64)) ReadSeekCloser

NewRequestProgress adds progress reporting to an HTTP request's body stream.

func NopCloser 

func NopCloser(rs io.ReadSeeker) ReadSeekCloser

NopCloser returns a ReadSeekCloser with a no-op close method wrapping the provided io.ReadSeeker.

type Request 

type Request struct {
	*http.Request
	// contains filtered or unexported fields
}

Request is an abstraction over the creation of an HTTP request as it passes through the pipeline. Don't use this type directly, use NewRequest() instead.

func NewRequest 

func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*Request, error)

NewRequest creates a new Request with the specified input.

func (*Request) Close 

func (req *Request) Close() error

Close closes the request body.

func (*Request) MarshalAsByteArray 

func (req *Request) MarshalAsByteArray(v []byte, format Base64Encoding) error

MarshalAsByteArray will base-64 encode the byte slice v, then calls SetBody. The encoded value is treated as a JSON string.

func (*Request) MarshalAsJSON 

func (req *Request) MarshalAsJSON(v interface{}) error

MarshalAsJSON calls json.Marshal() to get the JSON encoding of v then calls SetBody.

func (*Request) MarshalAsXML 

func (req *Request) MarshalAsXML(v interface{}) error

MarshalAsXML calls xml.Marshal() to get the XML encoding of v then calls SetBody.

func (*Request) Next 

func (req *Request) Next() (*http.Response, error)

Next calls the next policy in the pipeline. If there are no more policies, nil and ErrNoMorePolicies are returned. This method is intended to be called from pipeline policies. To send a request through a pipeline call Pipeline.Do().

func (*Request) OperationValue 

func (req *Request) OperationValue(value interface{}) bool

OperationValue looks for a value set by SetOperationValue().

func (*Request) RewindBody 

func (req *Request) RewindBody() error

RewindBody seeks the request's Body stream back to the beginning so it can be resent when retrying an operation.

func (*Request) SetBody 

func (req *Request) SetBody(body ReadSeekCloser, contentType string) error

SetBody sets the specified ReadSeekCloser as the HTTP request body.

Example

Code:play  

package main

import (
	"context"
	"log"
	"net/http"
	"strings"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
)

func main() {
	req, err := azcore.NewRequest(context.Background(), http.MethodPut, "https://contoso.com/some/endpoint")
	if err != nil {
		log.Fatal(err)
	}
	body := strings.NewReader("this is seekable content to be uploaded")
	err = req.SetBody(azcore.NopCloser(body), "text/plain")
	if err != nil {
		log.Fatal(err)
	}
}

func (*Request) SetMultipartFormData 

func (req *Request) SetMultipartFormData(formData map[string]interface{}) error

SetMultipartFormData writes the specified keys/values as multi-part form fields with the specified value. File content must be specified as a ReadSeekCloser. All other values are treated as string values.

func (*Request) SetOperationValue 

func (req *Request) SetOperationValue(value interface{})

SetOperationValue adds/changes a mutable key/value associated with a single operation.

func (*Request) SkipBodyDownload 

func (req *Request) SkipBodyDownload()

SkipBodyDownload will disable automatic downloading of the response body.

func (*Request) Telemetry 

func (req *Request) Telemetry(v string)

Telemetry adds telemetry data to the request. If telemetry reporting is disabled the value is discarded.

type RetryOptions 

type RetryOptions struct {
	// MaxRetries specifies the maximum number of attempts a failed operation will be retried
	// before producing an error.
	// The default value is three.  A value less than zero means one try and no retries.
	MaxRetries int32

	// TryTimeout indicates the maximum time allowed for any single try of an HTTP request.
	// This is disabled by default.  Specify a value greater than zero to enable.
	// NOTE: Setting this to a small value might cause premature HTTP request time-outs.
	TryTimeout time.Duration

	// RetryDelay specifies the initial amount of delay to use before retrying an operation.
	// The delay increases exponentially with each retry up to the maximum specified by MaxRetryDelay.
	// The default value is four seconds.  A value less than zero means no delay between retries.
	RetryDelay time.Duration

	// MaxRetryDelay specifies the maximum delay allowed before retrying an operation.
	// Typically the value is greater than or equal to the value specified in RetryDelay.
	// The default Value is 120 seconds.  A value less than zero means there is no cap.
	MaxRetryDelay time.Duration

	// StatusCodes specifies the HTTP status codes that indicate the operation should be retried.
	// The default value is the status codes in StatusCodesForRetry.
	// Specifying an empty slice will cause retries to happen only for transport errors.
	StatusCodes []int
}

RetryOptions configures the retry policy's behavior. All zero-value fields will be initialized with their default values.

type TelemetryOptions 

type TelemetryOptions struct {
	// Value is a string prepended to each request's User-Agent and sent to the service.
	// The service records the user-agent in logs for diagnostics and tracking of client requests.
	Value string

	// ApplicationID is an application-specific identification string used in telemetry.
	// It has a maximum length of 24 characters and must not contain any spaces.
	ApplicationID string

	// Disabled will prevent the addition of any telemetry data to the User-Agent.
	Disabled bool
}

TelemetryOptions configures the telemetry policy's behavior.

type TokenCredential 

type TokenCredential interface {
	Credential
	// GetToken requests an access token for the specified set of scopes.
	GetToken(ctx context.Context, options TokenRequestOptions) (*AccessToken, error)
}

TokenCredential represents a credential capable of providing an OAuth token.

type TokenRequestOptions 

type TokenRequestOptions struct {
	// Scopes contains the list of permission scopes required for the token.
	Scopes []string
	// TenantID contains the tenant ID to use in a multi-tenant authentication scenario, if TenantID is set
	// it will override the tenant ID that was added at credential creation time.
	TenantID string
}

TokenRequestOptions contain specific parameter that may be used by credentials types when attempting to get a token.

type Transporter 

type Transporter interface {
	// Do sends the HTTP request and returns the HTTP response or error.
	Do(req *http.Request) (*http.Response, error)
}

Transporter represents an HTTP pipeline transport used to send HTTP requests and receive responses.

Source Files

core.go credential.go doc.go error.go etag.go policy_anonymous_credential.go policy_body_download.go policy_http_header.go policy_logging.go policy_retry.go policy_telemetry.go poller.go progress.go request.go response.go transport_default_http_client.go version.go

Directories

PathSynopsis
logPackage log provides functionality for configuring logging facilities.
Version
v0.18.1
Published
Aug 20, 2021
Platform
windows/amd64
Imports
24 packages
Last checked
now –

Tools for package owners.