An Edge Lambda Function is a compute resource that runs your code at CDN edge locations, bringing it closer to your users to reduce latency and improve performance. These functions are globally distributed, ensuring that requests are handled by the nearest location.

Edge Lambdas are serverless, which means Stacktape manages the infrastructure, security, and scaling for you. They support Node.js and Python runtimes and follow a pay-per-use model, so you only pay for the execution time you consume.

Common use cases include user authentication, request validation, and cookie manipulation.

Under the hood

Stacktape uses Lambda@Edge to power Edge Lambda Functions. These functions are associated with a CDN and are triggered by CDN events—either when a request is made to the CDN (onRequest) or when the CDN is about to send a response back to the user (onResponse).

When to use

Advantages

• Low latency: By executing code closer to the end-user, you can significantly improve your application's performance.
• Scalability: Edge Lambdas automatically scale with the number of incoming requests.
• Pay-per-use: You are billed only for the compute time you use, measured in milliseconds.

Disadvantages

• Limited execution environment: Edge lambdas triggered by onRequest or onResponse events are limited to 128MB of memory and a 5-second maximum execution time.

Basic usage

In the following example, an Edge Lambda Function validates the Authorization header of each incoming request. If the header is missing or invalid, the user is redirected to a login page.

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

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

The event payload delivered to your function depends on the trigger:

• onRequest event structure
• onResponse event structure

On request trigger

When a function is triggered by an onRequest event, you can either:

1. Return a response directly from the function: This bypasses the origin and serves the response immediately to the client.
2. Modify the request and forward it to the origin: You can alter the request (e.g., add headers) before it continues to the origin.

The following example demonstrates both:

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;
};

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

A function triggered by an onResponse event can modify the response from the origin before it's sent to the client. In this example, the function adds a Set-Cookie header to the response:

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;
};

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

Packaging for Edge Lambda Functions follows the same process as for regular Lambda functions. For more details, see the packaging documentation.

Logging

Accessing other resources

By default, Edge Lambda Functions cannot access other AWS resources. Permissions must be granted explicitly using IAM. Stacktape automatically handles permissions for essential services like logging.

You can grant additional permissions in two ways:

Using connectTo

The connectTo property simplifies granting access to other Stacktape-managed resources. It automatically configures the necessary IAM permissions and injects environment variables with connection details.

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

For more granular control, you can provide raw IAM role statements to define custom permissions.

API reference