Overview

• Edge lambda function is a scalable and highly available computing resource that runs your code closer to users of your application, improving performance and latency.

• Functions are globally distributed across regional CDN cache locations (13 locations spread across the globe), which makes it possible to execute them closer to the end user

• Lambda functions are "serverless" and fully managed. You don't have to worry about provisioning and managing servers, container and OS security, patching, scaling & many other DevOps tasks.

• Supported runtimes are Node.js (Javascript and Typescript) and Python.

• Similarly to regular Lambda Functions, you only pay for the compute time you use - there is no charge when your code is not running.

• Use-cases for Edge lambda functions: performing user authentication, cookie inspection, validation of requests, and many more.

Under the hood

Under the hood, Stacktape uses Lambda@Edge. Lambda@Edge functions are always associated with CDNs and are triggered when request/response is sent to/from the CDN.

When to use

Advantages

• Low latency - By running code closer to end user, latency and overall performance is improved.
• Scalability - Run your code without necessity to manage any infrastructure. Similarly to regular functions, Edge lambda functions provide high scalability.
• Pay-per-use - You only pay for the compute time you consume (rounded to 1ms). Refer to Lambda@Edge pricing in AWS docs.

Disadvantages

• Limited execution environment - (Applies to onRequest/onResponse lambdas) Your Edge lambda functions are limited to 128MB of memory and maximum execution time of 5 seconds.

Basic usage

In the following example we are using edge-lambda-function to validate Authorization header of each incoming user request. If user is not authorized, he is redirected to login page.

YAML
TypeScript
Copy
resources:
  authFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: auth-function.ts

  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true
        edgeFunctions:
          onRequest: authFunction

Copy
const validateAuthorizationToken = (token) => {
  // perform some validation
  return true;
};

export default async (event) => {
  const { request } = event.Records[0].cf;
  const { headers } = request;

  const authorizationToken = headers.authorization?.[0]?.value;

  const userAuthorized = validateAuthorizationToken(authorizationToken);

  // if user is not authorized, redirect him to login page
  if (!userAuthorized) {
    return {
      status: '302',
      headers: {
        location: [
          {
            key: 'Location',
            value: '/login'
          }
        ],
        'cache-control': [
          {
            key: 'Cache-Control',
            value: 'no-cache, no-store, max-age=0, must-revalidate'
          }
        ]
      }
    };
  }

  // after we validated that user is authorized, we can return the request
  // request will be forwarded to origin
  return request;
};

Event structure

Event delivered to the function differs based on whether you are using onRequest or onResponse trigger:

• Event structure for onRequest function
• Event structure for onResponse function

On request trigger

When using onRequest trigger with edge-lambda-function you can:

1. Return response from function - In this case the response is served to the client directly and the request is NOT forwarded to the origin.
2. Forward request to origin - You can modify the request (path, body, headers ...) before forwarding to origin or you can forward it as is.

Following example code combines both options:

• If user is authorized - forwards request to the origin
• If user is not authorized - return redirect response to login page

Copy
const validateAuthorizationToken = (token) => {
  // perform some validation
  return true;
};

export default async (event) => {
  const { request } = event.Records[0].cf;
  const { headers } = request;

  const authorizationToken = headers.authorization?.[0]?.value;

  const userAuthorized = validateAuthorizationToken(authorizationToken);

  // if user is not authorized, redirect him to login page
  if (!userAuthorized) {
    return {
      status: '302',
      headers: {
        location: [
          {
            key: 'Location',
            value: '/login'
          }
        ],
        'cache-control': [
          {
            key: 'Cache-Control',
            value: 'no-cache, no-store, max-age=0, must-revalidate'
          }
        ]
      }
    };
  }

  // after we validated that user is authorized, we can return the request
  // request will be forwarded to origin
  return request;
};

YAML
TypeScript
Copy
resources:
  authFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: auth-function.ts

  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true
        edgeFunctions:
          onRequest: authFunction

On response trigger

When using onResponse trigger with edge-lambda-function you can modify the response before returning.

In following example we are using it to set response cookie.

Copy
export default async (event) => {
  const { response } = event.Records[0].cf;

  response.headers['set-cookie'] = [
    {
      key: 'Set-Cookie',
      value: 'my-experimental-cookie=cookie-value'
    }
  ];

  return response;
};

YAML
TypeScript
Copy
resources:
  cookieFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: set-cookie.ts

  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true
        edgeFunctions:
          onResponse: cookieFunction

Packaging

Refer to packaging docs.

Logging

Accessing other resources

• For most of the AWS resources, resource-to-resource communication is not allowed by default. This helps to enforce security and resource isolation. Access must be explicitly granted using IAM (Identity and Access Management) permissions.

• Stacktape automatically handles IAM permissions for the underlying AWS services that it creates (i.e. granting cdn lambda function permission to write logs to Cloudwatch).

• If your function needs to communicate with other infrastructure components, you need to add permissions manually. You can do this in 2 ways listed below.

Using connectTo

• List of resource names or AWS services that this function will be able to access (basic IAM permissions will be granted automatically). Granted permissions differ based on the resource.
• Works only for resources managed by Stacktape in resources section (not arbitrary Cloudformation resources)
• This is useful if you don't want to deal with IAM permissions yourself. Handling permissions using raw IAM role statements can be cumbersome, time-consuming and error-prone. Moreover, when using connectTo property, Stacktape automatically injects information about resource you are connecting to as environment variables into your compute resource.

YAML
TypeScript
Copy
resources:
  authFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: auth-function.ts
      connectTo:
        # access to the dynamo table
        - myDynamoTable
        # access to AWS SES
        - aws:ses

  myDynamoTable:
    type: dynamo-db-table
    properties:
      primaryKey:
        partitionKey:
          name: id
          type: string

Using iamRoleStatements

• List of raw IAM role statement objects. These will be appended to the function's role.
• Allows you to set granular control over your function's permissions.
• Can be used to give access to any Cloudformation resource

API reference