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)
67 package middleware
68