Work with requests and responses

To use Lambda@Edge requests and responses, see the following topics:

Use Lambda@Edge functions with origin failover

You can use Lambda@Edge functions with CloudFront distributions that you've set up with origin groups, for example, for origin failover that you configure to help ensure high availability. To use a Lambda function with an origin group, specify the function in an origin request or origin response trigger for an origin group when you create the cache behavior.

For more information, see the following:

Generate HTTP responses in request triggers

When CloudFront receives a request, you can use a Lambda function to generate an HTTP response that CloudFront returns directly to the viewer without forwarding the response to the origin. Generating HTTP responses reduces the load on the origin, and typically also reduces latency for the viewer.

Some common scenarios for generating HTTP responses include the following:

A Lambda@Edge function can generate an HTTP response when the following CloudFront events occur:

To see some sample code for generating HTTP responses, see Lambda@Edge example functions. You can also replace the HTTP responses in response triggers. For more information, see Update HTTP responses in origin response triggers.

Programming model

This section describes the programming model for using Lambda@Edge to generate HTTP responses.

Response object

The response you return as the result parameter of the callback method should have the following structure (note that only the status field is required).

const response = {
    body: 'content',
    bodyEncoding: 'text' | 'base64',
    headers: {
        'header name in lowercase': [{
            key: 'header name in standard case',
            value: 'header value'
         }],
         ...
    },
    status: 'HTTP status code (string)',
    statusDescription: 'status description'
};

The response object can include the following values:

Errors

The following are possible errors for generated HTTP responses.

Required fields

The status field is required.

All other fields are optional.

Update HTTP responses in origin response triggers

When CloudFront receives an HTTP response from the origin server, if there is an origin-response trigger associated with the cache behavior, you can modify the HTTP response to override what was returned from the origin.

Some common scenarios for updating HTTP responses include the following:

You can also replace the HTTP responses in viewer and origin request events. For more information, see Generate HTTP responses in request triggers.

When you're working with the HTTP response, Lambda@Edge does not expose the body that is returned by the origin server to the origin-response trigger. You can generate a static content body by setting it to the desired value, or remove the body inside the function by setting the value to be empty. If you don't update the body field in your function, the original body returned by the origin server is returned back to viewer.

Access the request body by choosing the include body option

You can opt to have Lambda@Edge expose the body in a request for writable HTTP methods (POST, PUT, DELETE, and so on), so that you can access it in your Lambda function. You can choose read-only access, or you can specify that you'll replace the body.

To enable this option, choose Include Body when you create a CloudFront trigger for your function that's for a viewer request or origin request event. For more information, see Add triggers for a Lambda@Edge function, or to learn about using Include Body with your function, see Lambda@Edge event structure.

Scenarios when you might want to use this feature include the following:

For sample code, see Lambda@Edge example functions.