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