1// Package middleware provides transport agnostic middleware for decorating SDK
 2// handlers.
 3//
 4// The Smithy middleware stack provides ordered behavior to be invoked on an
 5// underlying handler. The stack is separated into steps that are invoked in a
 6// static order. A step is a collection of middleware that are injected into a
 7// ordered list defined by the user. The user may add, insert, swap, and remove a
 8// step's middleware. When the stack is invoked the step middleware become static,
 9// and their order cannot be modified.
10//
11// A stack and its step middleware are **not** safe to modify concurrently.
12//
13// A stack will use the ordered list of middleware to decorate a underlying
14// handler. A handler could be something like an HTTP Client that round trips an
15// API operation over HTTP.
16//
17// Smithy Middleware Stack
18//
19// A Stack is a collection of middleware that wrap a handler. The stack can be
20// broken down into discreet steps. Each step may contain zero or more middleware
21// specific to that stack's step.
22//
23// A Stack Step is a predefined set of middleware that are invoked in a static
24// order by the Stack. These steps represent fixed points in the middleware stack
25// for organizing specific behavior, such as serialize and build. A Stack Step is
26// composed of zero or more middleware that are specific to that step. A step may
27// define its own set of input/output parameters the generic input/output
28// parameters are cast from. A step calls its middleware recursively, before
29// calling the next step in the stack returning the result or error of the step
30// middleware decorating the underlying handler.
31//
32// * Initialize: Prepares the input, and sets any default parameters as needed,
33// (e.g. idempotency token, and presigned URLs).
34//
35// * Serialize: Serializes the prepared input into a data structure that can be
36// consumed by the target transport's message, (e.g. REST-JSON serialization).
37//
38// * Build: Adds additional metadata to the serialized transport message, (e.g.
39// HTTP's Content-Length header, or body checksum). Decorations and
40// modifications to the message should be copied to all message attempts.
41//
42// * Finalize: Performs final preparations needed before sending the message. The
43// message should already be complete by this stage, and is only alternated to
44// meet the expectations of the recipient, (e.g. Retry and AWS SigV4 request
45// signing).
46//
47// * Deserialize: Reacts to the handler's response returned by the recipient of
48// the request message. Deserializes the response into a structured type or
49// error above stacks can react to.
50//
51// Adding Middleware to a Stack Step
52//
53// Middleware can be added to a step front or back, or relative, by name, to an
54// existing middleware in that stack. If a middleware does not have a name, a
55// unique name will be generated at the middleware and be added to the step.
56//
57//     // Create middleware stack
58//     stack := middleware.NewStack()
59//
60//     // Add middleware to stack steps
61//     stack.Initialize.Add(paramValidationMiddleware, middleware.After)
62//     stack.Serialize.Add(marshalOperationFoo, middleware.After)
63//     stack.Deserialize.Add(unmarshalOperationFoo, middleware.After)
64//
65//     // Invoke middleware on handler.
66//     resp, err := stack.HandleMiddleware(ctx, req.Input, clientHandler)
67package middleware