@specprotected/spec-proxy-cloudflare-worker

Spec Proxy Cloudflare Worker API Integration

This document describes a method of integrating with Spec Proxy through a Cloudflare Edge Worker.

Why use a Cloudflare 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.

How you would like to configure these values is up to you. For Cloudflare, you can use Cloudflare Environment Variables, for example, which allows users to configure the behavior of Spec Proxy in an easy and flexible way.

This library is powered by our more generic Spec Proxy Service Worker integration. Please see that library's documentation for more implementation details and information about configuration options.

Configuration Options

We provide a few configuration options for how traffic should be handled by the edge worker. Read more about these options in the README for our underlying edge worker library.

Right, how do I use this?

Using our library is simple. Let's start with an example.

// Import the Spec Proxy library function
import { specProxyProcess } from "@specprotected/spec-proxy-cloudflare-worker";

// Normal Edge Worker event listener
addEventListener("fetch", (event) => {
  // If we don't catch the exception, fail open to original traffic path
  event.passThroughOnException();

  // Our library processes the request and returns a new, modified one back to you.
  // Please ensure that you use the returned request as the destination request
  // of your worker script. This will ensure that traffic is routed appropriately.
  let request = specProxyProcess(event, {
    // Set to false to mirror traffic and send the original request!
    inlineMode: true,
  });

  // This is the simplest form where the worker script doesn't do anything else
  event.respondWith(request);
});

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.

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

addEventListener("fetch", (event) => {
  // if we don't catch the exception, fail open to original traffic path
  event.passThroughOnException();

  // configuration to call our Spec library
  let config = {
    inlineMode: true,
  };

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