AWS Edge@Lambda

Introduction

This guide will create two separate Edge@Lambda function bundles: one for the origin request and another for the origin response. The origin request function will package the request for processing by the Spec Platform, while the origin response function will augment the response for proper Customer Journey Security.

Prerequisites

• An existing CloudFront distribution.
• Refer to the configuration options available for the workers in configuration, also check out the known limitations below.
• Use your favorite JavaScript package installer (yarn or npm)to install the following package into your lambda project.
  • NPM Spec Proxy AWS Edge@Lambda
• An Origin Request bundle
• An Origin Response bundle

Instructions

Please note the following:

• All Edge@Lambdas must be created in the us-east-1 region in order to be associated to a CloudFront distribution. CloudFront will still replicate this function in other regions based on viewer request.
• The function must not have environment variables. Everything in a replicated edge function must be self-contained.
• The function cannot be placed inside a VPC, and there is no control of egress.

Review the AWS documentation for Lambda@Edge for best practices and more information.

Add Origin Request Edge@Lambda

1. Create a new Lambda function in the AWS console in the us-east-1 region.
2. Use the AWS managed Edge@Lambda service role.
3. Upload the Origin Request bundle to the console.
4. Publish a new version of the lambda bundle.
5. Copy the ARN including the version.
6. In the AWS CloudFront console, select the distribution to which the Lambda will be added.
7. Under behaviors, find the route that should be protected by Spec.
8. Paste the ARN into the Origin Request section.
9. Check "include body" option.
10. Save and wait for Edge@Lambda to propagate.

Add Origin Response Edge@Lambda

1. Create a new Lambda function in the AWS console in the us-east-1 region.
2. Use the AWS managed Edge@Lambda service role.
3. Upload the Origin Response bundle to the console.
4. Publish a new version of the Lambda bundle.
5. Copy the ARN including the version.
6. In the CloudFront console, select the distribution to which the Lambda will be added.
7. Under behaviors, find the route that should be protected by Spec.
8. Paste the ARN of the origin-response-lambda into the Origin Response section.
9. Check "include body" option.
10. Save and wait for Edge@Lambda to propagate.

Confirm the installation

1. Requests to the routes protected by the Spec Platform should behave normally.
2. Any logging added to the Code Bundles should appear in the logs. See tips below.

Lambda Function Code Bundles

Spec provides the Code Bundles as public NPM packages. They are built using TypeScript and designed to work alongside other edge worker functionality.

Use your favorite JavaScript package installer (yarn or npm) to install the following package into the project with your Lambda code.

• NPM Spec Proxy AWS Edge@Lambda

Building an Origin Request Bundle

The following snippet is the minimum amount of code required to create the origin request Edge@Lambda bundle:

import { specProxyProcessRequest } from "@specprotected/spec-proxy-aws-edge-lambda";
import { CloudFrontRequestEvent } from "aws-lambda";

const config = {
    disableSpecProxy: false,
    inlineMode: false
}

export const handler = async (event: CloudFrontRequestEvent) => {
    return await specProxyProcessRequest(event, config);
}

Check Edge Workers page for config options

Building an Origin Response Bundle

The process for this should be very similar to the Origin Request bundle, with a slight variation on the methods we are calling to handle the response:

import { specProxyProcessResponse } from "@specprotected/spec-proxy-aws-edge-lambda";
import { CloudFrontResponseEvent } from "aws-lambda";

const config = {
    disablespecproxy: false,
    inlinemode: false
}

export const handler = async (event: CloudFrontResponseEvent) => {
    return await specProxyProcessResponse(event, config);
}

Check Edge Workers page for config options

Limitations of Edge@Lambdas

Before using this integration, please be aware of the applicable Lambda@Edge limitations set by AWS:

• The timeout for an Edge@Lambda is 5 seconds.
  • If Spec and origin server combined take more than 5 seconds to respond, the Edge@Lambda will return a 502 error.
• The max memory can be 128MB.
  • Our library is very compact and requires minimal processing resources. However this limit can come into play when integrating with existing functions that are heavy in business logic.
  • Large responses may also trigger this memory limit.

Lambda@Edge Tips

• For more information on working with Lambdas and TypeScript:
  • AWS Building Functions with TypeScript
• Since there is no debugger in Edge@Lambdas, it can be helpful to add log statements in the code for the entire event object and view the logs in CloudWatch.
• CloudWatch logs will be in the region closest to the viewer. It helps to know which region you are closest to when trying to access these logs.
• In order to deploy a new Edge@Lambda, you must first create a new version. You can't use $LATEST to refer to an Edge@Lambda in the CloudFront console.