Spec Proxy Service Worker API Integration

This document describes a method of integrating with Spec Proxy through a Content Delivery Network (CDN) tool called an Edge Worker.

This is our generic service worker library. Specific platform libraries are built on top of this one. Use the following links to see platform-specific examples:

• Cloudflare
• Fastly

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

What is an Edge Worker?

Edge Workers are, simply put, a deployment of a unit of code "at the edge of the network". What this really means is that it runs very close to the originating request in terms of geolocation. This is a powerful method of deploying logic and functionality at a large scale without much effort. View the documentation of the following currently supported products to become more familiar with how they work.

• Cloudflare Edge Workers
• Fastly Compute@Edge

Why use an Edge Worker 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.

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. Note: Do not turn this on without contacting your Spec representative. | | 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 | | disableSpecTraffic | Boolean | none | When set to true, disables routing traffic to Spec Proxy only through the /spec_traffic path prefix. Generally, you do not want disable this feature, but it's provided so customers can control routing to this prefix. |

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

Please use the platform-specific library documentation for examples:

• Cloudflare
• Fastly

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.

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