AWS Documentation » Amazon CloudFront » Developer Guide » Using CloudFront with Lambda@Edge » Generating HTTP Responses in Request Triggers

Generating 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:

• Returning a small web page to the viewer

• Returning an HTTP 301 or 302 status code to redirect the user to another web page

• Returning an HTTP 401 status code to the viewer when the user hasn't authenticated

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

Viewer request events

When a function is triggered by a viewer request event, CloudFront returns the response to the viewer and doesn't cache it.

Origin request events

When a function is triggered by an origin request event, CloudFront checks the edge cache for a response that was previously generated by the function.

• If the response is in the cache, the function isn't executed and CloudFront returns the cached response to the viewer.

• If the response isn't in the cache, the function is executed, CloudFront returns the response to the viewer, and also caches it.

To see some sample code for generating HTTP responses, see field-level encryption. You can also replace the HTTP responses in response triggers. For more information, see Updating 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',
    statusDescription: 'status description'
};

The response object can include the following values:

body

The body, if any, that you want CloudFront to return in the generated response.

bodyEncoding

The encoding for the value that you specified in the body. The only valid encodings are text and base64. If you include body in the response object but omit bodyEncoding, CloudFront treats the body as text.

If you specify bodyEncoding as base64 but the body is not valid base64, CloudFront returns an error.

headers

Headers that you want CloudFront to return in the generated response. Note the following:

• The keys in the headers object are lowercase versions of standard HTTP header names. Using lowercase keys gives you case-insensitive access to the header values.

• Each header (for example, headers["accept"] or headers["host"]) is an array of key-value pairs. For a given header, the array contains one key-value pair for each value in the generated response. For example, if you want to include 3 values in the host header, the headers["host"] array will contain 3 key-value pairs.

• key is the case-sensitive name of the header as it appears in an HTTP request; for example, accept or host.

• value is a header value.

For information about restrictions on header usage, see Headers.

status

The HTTP status code that you want CloudFront to use for the following:

• Return in the response

• Cache in the CloudFront edge cache, when the response was generated by a function that was triggered by an origin request event

• Log in CloudFront Access Logs

If the status value isn't between 200 and 599, CloudFront returns an error to the viewer.

statusDescription

The description that you want CloudFront to return in the response, to accompany the HTTP status code. You don't need to use standard descriptions, such as OK for an HTTP status code of 200.

Errors

The following are possible errors for generated HTTP responses.

Response Contains a Body and Specifies 204 (No Content) for Status

When a function is triggered by a viewer request, CloudFront returns an HTTP 502 status code (Bad Gateway) to the viewer when both of the following are true:

• The value of status is 204 (No Content)

• The response includes a value for body

This is because Lambda@Edge imposes the optional restriction found in RFC 2616, which states that an HTTP 204 response does not need to contain a message body.

Limits on the Size of the Generated Response

The maximum size of a response that is generated by a Lambda function (including the headers and body) depends on the event that triggered the function:

• Viewer request events – 40 KB

• Origin request events – 1 MB

If the response is larger than the allowed size, CloudFront returns an HTTP 502 status code (Bad Gateway) to the viewer.

Required Fields

The status field is required.

All other fields are optional.