Edge Functions

• This article assumes that you are familiar with our CDN-as-Code approach for defining rules.
• Edge Functions requires activation. Contact your account manager or our sales department at 1 (866) 200 - 5463 to upgrade your account.

Prerequisites #

• An Edgio account. Sign up for free.
• An Edgio property. Learn how to create a property.
• Node.js. View supported versions and installation steps.
• Edgio CLI.

Install the Edgio CLI #

1npm i -g @edgio/cli@latest

Defining Edge Functions #

• Storing your standalone JavaScript code as a file with a js file extension.
• Setting an edge_function property within your routes.[js|ts]. Set this string property to the relative path to your edge function.
  JavaScript./routes.js

  Copy

  1import {Router} from '@edgio/core/router';
  2export default new Router()
  3  .get('/', {
  4    edge_function: './edge-functions/index.js',
  5  })
  6  .match('/api/*', {
  7    edge_function: './edge-functions/api.js',
  8  });

1/**
2 * Handles an HTTP request and returns a response.
3 *
4 * @async
5 * @param {Request} request - Represents the incoming request.
6 * @param {Object} context - Provides additional information about the request and environment.
7 * @param {Object} context.client - The client's network information.
8 * @param {Object} context.device - The client's device capabilities.
9 * @param {Object} context.environmentVars - Environment variables as defined in the Developer Console.
10 * @param {Object} context.geo - The client's geo location.
11 * @param {Object} context.metrics - Provides functions for injecting metrics into your edge function.
12 * @param {Function} context.metrics.add - Adds a value to the metric with the given ID.
13 * @param {Function} context.metrics.startTimer - Starts a timer for the metric with the given ID. Only one timer can be active at a time for a given metric ID.
14 * @param {Function} context.metrics.stopTimer - Stops a timer for the metric with the given ID.
15 * @param {Object} context.origins - Origin servers as defined in the Edgio Console or the edgio.config.js file.
16 * @param {Object} context.requestVars - Information about this property including values set using Set Variables.
17 * @returns {Response | Promise<Response>}
18 */
19export async function handleHttpRequest(request, context) {
20  // ... function code ...
21}

Edge Function Initialization Script (Optional) #

1import {Router} from '@edgio/core/router';
2
3export default new Router({
4  // Specify an edge function initialization script
5  edge_function_init_script: './edge-functions/init.js',
6}).get('/', {
7  edge_function: './edge-functions/main.js',
8});

1/**
2 * @async
3 * @param {Object} context - Provides additional information about the request and environment.
4 * @returns {void}
5 */
6export async function handleHttpInit(context) {
7  // ... function code ...
8}

• Execution Context: It’s important to note that certain parts of the context, like geo, client, and device, may not be relevant or populated during initialization as they are request-specific. The most relevant part of the context for initialization is context.environmentVars.
• Execution Frequency and State Preservation: The initialization code runs upon the first request received for any edge function within the project/bundle. After execution, the state is saved as a memory snapshot for subsequent executions of the project’s edge functions. These snapshots are specific to each backend cache server and will be periodically evicted based on internal criteria. Upon eviction, handleHttpInit will execute again for the next request.
• CPU/Memory Limitations: The initialization script shares the same CPU and memory limitations as the edge functions. This includes the execution time constraint (i.e., 50ms).
• Use Cases: An initialization script is ideal for computationally expensive operations like compiling regex, which is beneficial to perform once rather than in every edge function execution. However, operations like fetch are not recommended in this phase due to potential persistence of fetched data beyond desired periods.
• Consideration for Global State: Developers should be cautious when using the context to set up specific code or save data in the global scope during initialization, as it may persist and potentially lead to incorrect behavior across different requests.

1export async function handleHttpInit(context) {
2  // Set up a global regular expression for matching URLs
3  global.urlRegex = new RegExp('https://example.com');
4}

1export async function handleHttpRequest(request, context) {
2  // Access the global variable
3  if (global.urlRegex.test(request.url)) {
4    // ... function code ...
5  }
6}

Edge Function Parameters #

Metrics Functions #

Edge Function Namespace #

Request Class #

Supported Methods and Properties #

• Headers: Access the request headers using request.headers.
• Body: The request body can be read as:
  • ArrayBuffer: await request.arrayBuffer()
  • JSON: await request.json()
  • Text: await request.text()
• Method: request.method to get the HTTP method of the request.
• URL: request.url provides the full URL, and request.path gives the request path.
• Cloning: To clone a request without its body, use request.cloneWithoutBody().

Unsupported Methods and Properties #

• request.blob()
• request.cache
• request.credentials
• request.clone()
• request.destination
• request.formData()
• request.integrity
• request.mode
• request.redirect
• request.referrer
• request.referrerPolicy
• request.signal

Response Class #

Supported Methods and Properties #

• Headers: Access or modify the response headers using response.headers.
• Body: The response body can be interacted with using:
  • ArrayBuffer: await response.arrayBuffer()
  • JSON: await response.json()
  • Text: await response.text()
• Status: response.status to get the HTTP status code of the response. response.statusText provides the corresponding status text.
• URL: response.url provides the URL of the response.
• Redirected: response.redirected is a property that indicates whether the response is a result of a redirection.
  You may redirect a response up to 5 times before an exception is thrown.
• Redirection: Create a redirected response using Response.redirect(url, status).
• Cloning: To clone a response without its body, use response.cloneWithoutBody().

Unsupported Methods and Properties #

• response.blob()
• response.clone()
• response.formData()
• response.type

Responding to the Client #

1export async function handleHttpRequest(request, context) {
2  const defaultResponse = new Response('Hello World!');
3  const response = await fetch('https://your-server.com', {
4    edgio: {
5      // an origin name must be specified in the request
6      origin: 'web',
7    },
8  });
9
10  if (!response.ok) {
11    return defaultResponse;
12  }
13
14  return response;
15}

Origin Requests Using fetch() #

1module.exports = {
2  /* ... */
3  origins: [
4    {
5      // The name of the backend origin
6      name: 'web',
7
8      // Uncomment the following to override the host header sent from the browser when connecting to the origin
9      // override_host_header: 'example.com',
10
11      // The list of origin hosts to which to connect
12      hosts: [
13        {
14          // The domain name or IP address of the origin server
15          location: 'your-server.com',
16        },
17      ],
18
19      // Uncomment the following to configure a shield
20      // shields: { us_east: 'DCD' },
21    },
22  ],
23};

1export async function handleHttpRequest(request, context) {
2  const resp = await fetch('https://your-server.com', {
3    // an Edgio origin must be specified in the request
4    edgio: {
5      origin: 'web',
6    },
7  });
8
9  // handle the response as needed
10  /* ... */
11
12  // return the response to the client
13  return resp;
14}

1export async function handleHttpRequest(request, context) {
2  const fetch = createFetchForOrigin('web');
3
4  const resp = await fetch('https://your-server.com');
5
6  // handle the response as needed
7  /* ... */
8
9  // return the response to the client
10  return resp;
11}

1import {connect} from '@planetscale/database';
2import {createFetchForOrigin} from './polyfills';
3
4const fetch = createFetchForOrigin('planetscale');
5
6export async function handleHttpRequest(request, context) {
7  const env = context.environmentVars;
8
9  const config = {
10    host: env.PLANETSCALE_HOST,
11    username: env.PLANETSCALE_USERNAME,
12    password: env.PLANETSCALE_PASSWORD,
13    fetch,
14  };
15
16  const conn = connect(config);
17
18  // make a request to the PlanetScale API
19  /* ... */
20
21  // return the response to the client
22  return resp;
23}

1import createFetchForOrigin from './polyfills';
2
3export async function handleHttpRequest(request, context) {
4  const fetch = createFetchForOrigin('api');
5
6  // override the global fetch() function
7  global.fetch = fetch;
8
9  // make a request to the your API
10  /* ... */
11
12  // return the response to the client
13  return resp;
14}

edgio_self Origin #

1import {Router} from '@edgio/core/router';
2
3export default new Router()
4  // Incoming requests for `/products` are handled by an edge function
5  .get('/products', {
6    edge_function: './edge-functions/products.js',
7  })
8
9  // Incoming requests for `/promotions` are proxied to the origin server
10  .get('/promotions', {
11    origin: {
12      set_origin: 'web',
13    },
14  });

1export async function handleHttpRequest(request, context) {
2  // Fetch the promotions resource from the same property
3  const promosUrl = new URL('/promotions', request.url);
4  const resp = await fetch(promosUrl, {
5    edgio: {
6      origin: 'edgio_self',
7    },
8  });
9
10  // handle the response as needed (e.g., apply sale promotions to products)
11  /* ... */
12
13  // return the response to the client
14  return resp;
15}

1. Incoming Request for /products:
   • The incoming request matches the /products route and is handled by the edge function.
   • The edge function is invoked, which is configured to fetch another resource /promotions on the same property.
2. Internal Fetch to /promotions:
   • The edge function makes an internal fetch to/promotions as instructed by the edgio_self origin.
   • The incoming request for /promotions is processed by the corresponding route.
   • Applicable incoming request rules are applied.
   • The request is then forwarded to the origin server.
   • The origin server processes the request and returns a response.
   • Applicable response rules for /promotions are applied.
   • The response is then sent back to the edge function.
3. Returning the Final Response:
   • The edge function receives the response for /promotions.
   • It may further process this response and then generates its own response.
   • Applicable response rules for /products are applied.
   • Finally, the response for /products is sent back to the client.

Key Points#

• The edgio_self origin instructs edge functions to send fetch requests to itself.
• This capability is particularly useful for composing complex behaviors where different resources within the same property need to interact with each other.
• It ensures that each request, whether it’s an initial browser request or an internally generated fetch from an edge function, undergoes the appropriate set of rules and processing steps configured for its specific path.

Caching fetch() Requests #

Compressed Responses #

1async function handleRequest(request) {
2  // Modify the request to disallow compressed responses
3  const modifiedRequest = new Request(request, {
4    headers: new Headers({
5      ...request.headers,
6      'Accept-Encoding': 'identity', // Disallow compression methods like gzip or br
7    }),
8  });
9
10  // Fetch the response from the origin server
11  const response = await fetch(modifiedRequest);
12
13  // Assuming the response needs to be manipulated
14  let responseBody = await response.text(); // Get the response body as text
15  responseBody = responseBody.replace('foo', 'bar'); // Manipulate the response body
16
17  // Return the manipulated response to the client
18  return new Response(responseBody, response);
19}

Fetch Limitations #

• Be greater than or equal to 200.
• Be less than or equal to 599.
• Not be 204 or 304.

1export async function handleHttpRequest(request) {
2  /* ... */
3
4  // Remove headers that could cause the a response status of 204/304 to be returned.
5  const headersToRemove = [
6    'etag',
7    'if-modified-since',
8    'if-none-match',
9    'last-modified',
10  ];
11  headersToRemove.forEach((header) => request.headers.delete(header));
12
13  const response = await fetch(request.url, {
14    edgio: {
15      origin: 'web',
16    },
17    method: request.method,
18    headers: request.headers,
19  });
20
21  // handle the response as needed
22
23  return response;
24}

Testing Locally #

1. From the command line or terminal, type edgio dev.
2. Preview your website by loading https://127.0.0.1:3000 from within your preferred web browser.

Deploying Your Property #

1edgio deploy

Limitations of Edge Functions #

• Wall-time Timeout: 60s
• CPU Time Limit: 50ms
• Runtime Memory Limit: 4MB
• Code Package Size Limit: 512KB

12023-08-14T17:37:04Z - error - external - Schema validation error: properties.0.edge_functions.quickjs_bytecode_base64 exceeds maximum size. Max: 512000, got: 1514469
22023-08-14T17:37:04Z - error - external - Error: the server responded with status 400

Polyfills and Helpers #

• Buffer API
  JavaScript

  Copy

  1// 'buffer' polyfill is provided by the Edgio CLI
  2global.Buffer = require('buffer').Buffer;
  3
  4global.btoa = function (str) {
  5  return Buffer.from(str, 'binary').toString('base64');
  6};
  7
  8global.atob = function (b64Encoded) {
  9  return Buffer.from(b64Encoded, 'base64').toString('binary');
  10};

• process.env Namespace
  This namespace is not globally available in edge functions. You can define the following polyfill to set environment variables from the context object.
  JavaScript

  Copy

  1/**
  2 * Define a polyfill for 'process'
  3 */
  4global.process = global.process || {env: {}};
  5
  6/**
  7 * Sets environment variables from a given context.
  8 *
  9 * @param {Object} context - The context object containing environment variables.
  10 * @param {Object} context.environmentVars - Key-value pairs of environment variables.
  11 */
  12export function setEnvFromContext({environmentVars}) {
  13  Object.assign(process.env, environmentVars);
  14}

• URL Class
  This class, provided by the Edgio CLI, is compatible with the standard URL class.
  JavaScript

  Copy

  1let url = new URL('https://www.url.com/path');
  2url.port = 8080;
  3let newUrl = url.toString(); // newUrl will equal 'https://www.url.com:8080/path'

  JavaScript

  Copy

  1let url = new URL('/patha/pathb', 'https://www.url.com/');
  2let newUrl = url.toString(); // newUrl will equal 'https://www.url.com/patha/pathb'

• URLSearchParams Class
  This class, provided by the Edgio CLI, is compatible with the standard URLSearchParams class.
  JavaScript

  Copy

  1let url = new URL('https://www.url.com/path?a=b');
  2let params = url.searchParams;
  3params.set('c', 'one');
  4let newUrl = url.toString(); // newUrl will equal 'https://www.url.com/path?a=b&c=one'

Polyfill Limitations #

Helper Functions #

• createFetchForOrigin for the fetch() API
  This function returns a modified fetch() function that includes the origin server. This is useful for making multiple requests to the same origin or overriding the global function.
  Some third-party libraries let you specify a fetch() function. If you are unable to set this in your library, you can override the global one using this helper. See the Origin Requests Using fetch() section for more details.
  JavaScript

  Copy

  1/**
  2 * Creates a fetch function with an additional 'edgio' option to specify the origin. Example usage:
  3 *
  4 * // create a fetch function for the 'web' origin.
  5 * const fetch = createFetchForOrigin('web');
  6 * const response = await fetch('https://your-server.com');
  7 *
  8 * // override the global fetch() function
  9 * global.fetch = createFetchForOrigin('web');;
  10 *
  11 * @param {string} originName - The origin name defined in edgio.config.js.
  12 * @returns {function} - A modified fetch function.
  13 * @throws {Error} If the origin name is not provided.
  14 */
  15export default function createFetchForOrigin(originName) {
  16  if (!originName) {
  17    throw new Error(
  18      "'originName' is required and must be a name defined in edgio.config.js"
  19    );
  20  }
  21
  22  return (url, options = {}) => {
  23    const modifiedOptions = {
  24      ...options,
  25      edgio: {
  26        origin: originName,
  27      },
  28    };
  29    return fetch(url, modifiedOptions);
  30  };
  31}

• parseURL(url: string)
  This function parses a URL string and returns an object containing the URL’s components.
  JavaScript

  Copy

  1// Show all the possible values
  2parseURL('http://user:password@www.url.com:8080/one/two?a=b#hash')
  3{
  4  fragment: 'hash',
  5  host: 'www.url.com',
  6  password: 'password',
  7  path: [ 'one', 'two' ],
  8  port: 8080,
  9  query: 'a=b',
  10  scheme: 'http',
  11  username: 'user'
  12}
  13
  14// Show the minimum required values
  15parseURL('https://url.com/')
  16{
  17  fragment: null,
  18  host: 'url.com',
  19  password: '',
  20  path: [ '' ],
  21  port: null,
  22  query: null,
  23  scheme: 'https',
  24  username: ''
  25}
  26
  27// Returns null on empty string or string with bad url
  28parseURL('url.com')
  29null
  30
  31// Throws on non-string argument
  32parseURL() // will throw

Edge Function Examples #