Spec Proxy AWS Edge Lambda API Integration

This document describes a method of integrating with Spec Proxy through an AWS@Lambda CloudFront function.

This library is created specifically for AWS Edge@Lambdas, and will not work for other Cloud Service Providers.

If you are not using AWS, check the links to see other platform-specific examples:

• Cloudflare
• Fastly
• Akamai
• Generic Service Worker Lib

Please contact your Spec representative for more details or to ask any questions.

What is an Edge@Lambda?

An Edge Lambda, or Lambda@Edge, is a feature of AWS Lambda that allows you to run code closer to your end users by deploying it to AWS CloudFront locations worldwide. This enables low-latency and highly responsive interactions by executing functions in response to CloudFront events, such as requests or responses. Edge Lambdas can be used for tasks like modifying HTTP requests and responses, performing A/B testing, implementing authentication and authorization, or generating dynamic content at the edge, thus enhancing the performance and scalability of web applications.

• AWS Edge@Lambda
• CloudFront

Why use an Edge@Lambda with Spec Proxy?

Edge Workers allow you to integrate with Spec Proxy at the scale of the CDN provider. With our simple library implementation, everything is processed in the background so customer requests receive priority of handling. Integrating with our product is as easy as calling a single function, and we provide you with configuration options to choose how to pass traffic to Spec Proxy.

Examples

For inline mode, we require only an "origin request" edge@lambda to send traffic to Spec. Our service can then add a required cookie. Since the traffic is not going through Spec, and only a copy is sent, we also require an "origin-response" edge@lambda to add the spec cookie on the request.

Origin Request Example:

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

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

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

Notes:

• This should exist as a part of a behavior on origin-request of an existing CloudFront distribution.
• It should also include the body in the request.

Origin Response Example:

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

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

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

Notes:

• This should be on the same behavior as the other edge@lambda for origin-request
• This should be on the origin-response

Configuration Options

We provide a few configuration options for how traffic should be handled by the Cloudflare Worker.

| Variable | Type | Default | Description | |--------------------|---------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | disableSpecProxy | Boolean | false | Toggle between enabling or disabling Spec processing. When disabled (true), all traffic is routed directly to the customer's downstream origin, bypassing Spec completely. This setting causes all of the following settings to be ignored. | | inlineMode | Boolean | false | Toggle between two available processing modes. Inline mode (true) works by forwarding traffic through the Spec Trust Cloud for processing. This mode enables inline mitigations. Mirror mode (false) creates a copy of traffic to send to the Spec Trust Cloud for processing while the original message is forwarded directly to the customer's downstream origin. This mode does not allow for inline mitigations. | | percentageOfIPs | Number | 100 | Number representing the percentage of all IP addresses which should have traffic routed through Spec. The remaining percentage of IPs will be routed directly to the customer's downstream origin. This can be used for progressive onboarding / rollout. | | customerKey | String | none | A key provided by Spec to validate that traffic came from a customer-controlled service worker |

The inlineMode configuration option is the only option that changes how Spec Proxy itself behaves. For more details on what inline mode means and what features of Spec Proxy are available to you when running in inline mode, please contact your Spec representative.

The customerKey option provides extra validation that we are only processing traffic that originated from your service workers. In general, this is redundant for inline processing, since we are processing traffic destined for the customer

• [ ] origin and validating it with a customer-provided SSL certificate. For mirror mode configurations, while we only allow traffic into Spec Proxy from your edge platform's IP address ranges and do not return any data in the responses to mirrored traffic, using the customerKey option is recommended. If this option is provided, we will validate this key prior to processing any mirrored traffic. The key is encrypted in transit with the rest of your mirrored traffic.

Implementation Examples

There are two primary functions that are exported by this library:

• specProxyProcessRequest

  • This function should be used in an "origin request" lambda, so we process the request before the event reaches the downstream client origin. In mirror mode, this function simply packages a request for Spec, and returns the origin request to the origin. During inline operation, this function replaces the request origin object with one that points to Spec.

• specProxyProcessResponse

  • This function should be included in an "origin response" edge lambda, which will add the required spec cookie.

• Edge@Lambda Events

Please use the platform-specific library documentation for examples:

• Cloudflare
• Fastly
• Akamai
• Generic Service Worker Lib

Integrating alongside another library

We return a request to help make it a simple integration alongside other products. Unfortunately, though, Spec Proxy and other products may require the event object as an argument because this provides access to a suite of tools from the Service Worker API. In order for Spec Proxy to properly record the incoming requests, it's best to call our library first so we don't process data that has been manipulated by other libraries you may be using.

It can be useful to have a tool to provide the modified request to other libraries because the event object that's passed in is not modifiable. Whether Spec Proxy is mirrored or inline, it will create a new Request that must be used in the rest of your edge worker script. Here is how you can trick Spec Proxy into using a wrapper object that replaces the request property. This is essentially a proxy-object that allows us to modify parts of the incoming event, even though it is immutable. This technique can be used to pass an event wrapper to other libraries as well. You may need to provide access to some of the methods that other libraries require. The example below shows how to proxy access to the waitUntil event, which is the only thing our library requires besides the request object.

Note: The following example uses the generic service worker library, you should use the library specific to your platform and then implement the code below to wrap the event object. The generic service worker library below is incompatible with AWS.

import { specProxyProcess } from "@specprotected/spec-proxy-service-worker";

addEventListener("fetch", (event) => {
  // configuration to call our Spec library
  let config = {
    inlineMode: true,
  };

  // example of request modification happening prior to calling Spec Proxy
  let url = new URL(request.url);
  url.host = "https://somewhere.else"; // we modify the request in some way
  let request = new Request(url, event.request);

  // wrap up the event methods that the Spec Proxy library uses alongside the request
  let eventWrapper = {
    waitUntil: event.waitUntil.bind(event),
    request: request,
  };
  request = specProxyProcess(eventWrapper, config);

  event.respondWith(request);
});