middleware

Documentation

Overview

Package middleware provides transport agnostic middleware for decorating SDK handlers.

The Smithy middleware stack provides ordered behavior to be invoked on an underlying handler. The stack is separated into steps that are invoked in a static order. A step is a collection of middleware that are injected into a ordered list defined by the user. The user may add, insert, swap, and remove a step's middleware. When the stack is invoked the step middleware become static, and their order cannot be modified.

A stack and its step middleware are **not** safe to modify concurrently.

A stack will use the ordered list of middleware to decorate a underlying handler. A handler could be something like an HTTP Client that round trips an API operation over HTTP.

Smithy Middleware Stack

A Stack is a collection of middleware that wrap a handler. The stack can be broken down into discreet steps. Each step may contain zero or more middleware specific to that stack's step.

A Stack Step is a predefined set of middleware that are invoked in a static order by the Stack. These steps represent fixed points in the middleware stack for organizing specific behavior, such as serialize and build. A Stack Step is composed of zero or more middleware that are specific to that step. A step may define its own set of input/output parameters the generic input/output parameters are cast from. A step calls its middleware recursively, before calling the next step in the stack returning the result or error of the step middleware decorating the underlying handler.

* Initialize: Prepares the input, and sets any default parameters as needed, (e.g. idempotency token, and presigned URLs).

* Serialize: Serializes the prepared input into a data structure that can be consumed by the target transport's message, (e.g. REST-JSON serialization).

* Build: Adds additional metadata to the serialized transport message, (e.g. HTTP's Content-Length header, or body checksum). Decorations and modifications to the message should be copied to all message attempts.

* Finalize: Performs final preparations needed before sending the message. The message should already be complete by this stage, and is only alternated to meet the expectations of the recipient, (e.g. Retry and AWS SigV4 request signing).

* Deserialize: Reacts to the handler's response returned by the recipient of the request message. Deserializes the response into a structured type or error above stacks can react to.

Adding Middleware to a Stack Step

Middleware can be added to a step front or back, or relative, by name, to an existing middleware in that stack. If a middleware does not have a name, a unique name will be generated at the middleware and be added to the step.

// Create middleware stack
stack := middleware.NewStack()

// Add middleware to stack steps
stack.Initialize.Add(paramValidationMiddleware, middleware.After)
stack.Serialize.Add(marshalOperationFoo, middleware.After)
stack.Deserialize.Add(unmarshalOperationFoo, middleware.After)

// Invoke middleware on handler.
resp, err := stack.HandleMiddleware(ctx, req.Input, clientHandler)

Index

• func AddClientRequestIDMiddleware(stack *middleware.Stack) error
• func AddRawResponseToMetadata(stack *middleware.Stack) error
• func AddRecordResponseTiming(stack *middleware.Stack) error
• func AddRequestIDRetrieverMiddleware(stack *middleware.Stack) error
• func AddRequestUserAgentMiddleware(stack *middleware.Stack) error
• func AddSDKAgentKey(keyType SDKAgentKeyType, key string) func(*middleware.Stack) error
• func AddSDKAgentKeyValue(keyType SDKAgentKeyType, key, value string) func(*middleware.Stack) error
• func AddUserAgentKey(key string) func(*middleware.Stack) error
• func AddUserAgentKeyValue(key, value string) func(*middleware.Stack) error
• func GetAttemptSkew(metadata middleware.Metadata) (v time.Duration, ok bool)
• func GetEndpointSource(ctx context.Context) (v cybr.EndpointSource)
• func GetOperationName(ctx context.Context) (v string)
• func GetRawResponse(metadata middleware.Metadata) interface{}
• func GetRequestIDMetadata(metadata middleware.Metadata) (string, bool)
• func GetResponseAt(metadata middleware.Metadata) (v time.Time, ok bool)
• func GetServerTime(metadata middleware.Metadata) (v time.Time, ok bool)
• func GetServiceID(ctx context.Context) (v string)
• func GetSigningCredentials(ctx context.Context) (v cybr.Credentials)
• func GetSigningName(ctx context.Context) (v string)
• func SetEndpointSource(ctx context.Context, value cybr.EndpointSource) context.Context
• func SetRequestIDMetadata(metadata *middleware.Metadata, id string)
• func SetServiceID(ctx context.Context, value string) context.Context
• func SetSigningCredentials(ctx context.Context, value cybr.Credentials) context.Context
• func SetSigningName(ctx context.Context, value string) context.Context
• type ClientRequestID
  • func (r ClientRequestID) HandleBuild(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) (out middleware.BuildOutput, metadata middleware.Metadata, err error)
  • func (r *ClientRequestID) ID() string
• type RecordResponseTiming
  • func (a RecordResponseTiming) HandleDeserialize(ctx context.Context, in middleware.DeserializeInput, ...) (out middleware.DeserializeOutput, metadata middleware.Metadata, err error)
  • func (a *RecordResponseTiming) ID() string
• type RegisterServiceMetadata
  • func (s RegisterServiceMetadata) HandleInitialize(ctx context.Context, in middleware.InitializeInput, ...) (out middleware.InitializeOutput, metadata middleware.Metadata, err error)
  • func (s *RegisterServiceMetadata) ID() string
• type SDKAgentKeyType

Functions

func AddClientRequestIDMiddleware

func AddClientRequestIDMiddleware(stack *middleware.Stack) error

AddClientRequestIDMiddleware adds ClientRequestID to the middleware stack

func AddRawResponseToMetadata

func AddRawResponseToMetadata(stack *middleware.Stack) error

AddRawResponseToMetadata adds middleware to the middleware stack that store raw response on to the metadata.

func AddRecordResponseTiming

func AddRecordResponseTiming(stack *middleware.Stack) error

AddRecordResponseTiming adds RecordResponseTiming middleware to the middleware stack.

func AddRequestIDRetrieverMiddleware

func AddRequestIDRetrieverMiddleware(stack *middleware.Stack) error

AddRequestIDRetrieverMiddleware adds request id retriever middleware

func AddRequestUserAgentMiddleware

func AddRequestUserAgentMiddleware(stack *middleware.Stack) error

AddRequestUserAgentMiddleware registers a requestUserAgent middleware on the stack if not present.

func AddSDKAgentKey

func AddSDKAgentKey(keyType SDKAgentKeyType, key string) func(*middleware.Stack) error

AddSDKAgentKey retrieves a requestUserAgent from the provided stack, or initializes one.

func AddSDKAgentKeyValue

func AddSDKAgentKeyValue(keyType SDKAgentKeyType, key, value string) func(*middleware.Stack) error

AddSDKAgentKeyValue retrieves a requestUserAgent from the provided stack, or initializes one.

func AddUserAgentKey

func AddUserAgentKey(key string) func(*middleware.Stack) error

AddUserAgentKey retrieves a requestUserAgent from the provided stack, or initializes one.

func AddUserAgentKeyValue

func AddUserAgentKeyValue(key, value string) func(*middleware.Stack) error

AddUserAgentKeyValue retrieves a requestUserAgent from the provided stack, or initializes one.

func GetAttemptSkew

func GetAttemptSkew(metadata middleware.Metadata) (v time.Duration, ok bool)

GetAttemptSkew returns Attempt clock skew for response from metadata.

func GetEndpointSource

func GetEndpointSource(ctx context.Context) (v cybr.EndpointSource)

GetEndpointSource returns an endpoint source if set on context

func GetOperationName

func GetOperationName(ctx context.Context) (v string)

GetOperationName retrieves the service operation metadata from the context.

Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

func GetRawResponse

func GetRawResponse(metadata middleware.Metadata) interface{}

GetRawResponse returns raw response set on metadata

func GetRequestIDMetadata

func GetRequestIDMetadata(metadata middleware.Metadata) (string, bool)

GetRequestIDMetadata retrieves the request id from middleware metadata returns string and bool indicating value of request id, whether request id was set.

func GetResponseAt

func GetResponseAt(metadata middleware.Metadata) (v time.Time, ok bool)

GetResponseAt returns the time response was received at.

func GetServerTime

func GetServerTime(metadata middleware.Metadata) (v time.Time, ok bool)

GetServerTime returns the server time for response.

func GetServiceID

func GetServiceID(ctx context.Context) (v string)

GetServiceID retrieves the service id from the context.

Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

func GetSigningCredentials

func GetSigningCredentials(ctx context.Context) (v cybr.Credentials)

GetSigningCredentials returns the credentials that were used for signing if set on context.

func GetSigningName

func GetSigningName(ctx context.Context) (v string)

GetSigningName retrieves the service signing name from the context.

Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

Deprecated: This value is unstable. The resolved signing name is available in the signer properties object passed to the signer.

func SetEndpointSource

func SetEndpointSource(ctx context.Context, value cybr.EndpointSource) context.Context

SetEndpointSource sets endpoint source on context

func SetRequestIDMetadata

func SetRequestIDMetadata(metadata *middleware.Metadata, id string)

SetRequestIDMetadata sets the provided request id over middleware metadata

func SetServiceID

func SetServiceID(ctx context.Context, value string) context.Context

SetServiceID sets the service id on the context.

Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

func SetSigningCredentials

func SetSigningCredentials(ctx context.Context, value cybr.Credentials) context.Context

SetSigningCredentials sets the credentails used for signing on the context.

func SetSigningName

func SetSigningName(ctx context.Context, value string) context.Context

SetSigningName set or modifies the sigv4 or sigv4a signing name on the context.

Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

Deprecated: This value is unstable. Use WithSigV4SigningName client option funcs instead.

Types

type ClientRequestID

type ClientRequestID struct{}

ClientRequestID is a Smithy BuildMiddleware that will generate a unique ID for logical API operation invocation.

func (ClientRequestID) HandleBuild

func (r ClientRequestID) HandleBuild(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) (
	out middleware.BuildOutput, metadata middleware.Metadata, err error,
)

HandleBuild attaches a unique operation invocation id for the operation to the request

func (*ClientRequestID) ID

func (r *ClientRequestID) ID() string

ID the identifier for the ClientRequestID

type RecordResponseTiming

type RecordResponseTiming struct{}

RecordResponseTiming records the response timing for the SDK client requests.

func (RecordResponseTiming) HandleDeserialize

func (a RecordResponseTiming) HandleDeserialize(ctx context.Context, in middleware.DeserializeInput, next middleware.DeserializeHandler) (
	out middleware.DeserializeOutput, metadata middleware.Metadata, err error,
)

HandleDeserialize calculates response metadata and clock skew

func (*RecordResponseTiming) ID

func (a *RecordResponseTiming) ID() string

ID is the middleware identifier

type RegisterServiceMetadata

type RegisterServiceMetadata struct {
	ServiceID     string
	SigningName   string
	OperationName string
}

RegisterServiceMetadata registers metadata about the service and operation into the middleware context so that it is available at runtime for other middleware to introspect.

func (RegisterServiceMetadata) HandleInitialize

func (s RegisterServiceMetadata) HandleInitialize(
	ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler,
) (out middleware.InitializeOutput, metadata middleware.Metadata, err error)

HandleInitialize registers service metadata information into the middleware context, allowing for introspection.

func (*RegisterServiceMetadata) ID

func (s *RegisterServiceMetadata) ID() string

ID returns the middleware identifier.

type SDKAgentKeyType

type SDKAgentKeyType int

SDKAgentKeyType is the metadata type to add to the SDK agent string

const (
	APIMetadata SDKAgentKeyType
	OperatingSystemMetadata
	LanguageMetadata
	EnvironmentMetadata
	FeatureMetadata
	ConfigMetadata
	FrameworkMetadata
	AdditionalMetadata
	ApplicationIdentifier
)

The set of valid SDKAgentKeyType constants. If an unknown value is assigned for SDKAgentKeyType it will be mapped to AdditionalMetadata.