Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Service Workers

Supported Providers

Spec maintains a collection of NPM-hosted integration libraries to ensure seamless delivery of traffic from your preferred cloud provider to the Realtime Engine.
AWS Edge@Lambda
Cloudflare
Fastly

note

If Spec doesn't support a provider you need, contact your Product Success representative.

Configuration

Service Workers enable seamless integration with Spec at the CDN level. Our easy-to-use libraries handle everything in the background. The integration requires a single function call, with flexible configuration options for routing traffic to the Spec Platform.

The following are the configuration options that are common to all service workers:

KeyTypeDefaultNotes
disableSpecProxyBooleanfalseEnable or disable realtime processing. When disabled (true), all traffic bypasses Realtime Engine and goes directly to origin servers, ignoring all other settings.
inlineModeBooleanfalseSwitch between two realtime processing modes:
Active Inline (true) routes traffic through the Spec Trust Cloud for inline mitigations.

Mirror Mode (false) duplicates traffic for Spec processing while sending the original directly to the customer's origin, without inline mitigations.
percentageOfIPsNumber100The percentage of IP addresses to route through the Realtime Engine; the rest go directly to the customer's origin. Useful for gradual onboarding or rollout.
customerKeyStringnoneA key from Spec to verify that traffic originates from a customer-controlled service worker.

Service Worker Networking

Each of the supported provider-specific NPM packages wraps our core generic library:

The inlineMode configuration value determines which of the service worker's two primary networking behaviors is used: Mirror or Inline (which includes Active Inline and Pass Through modes). To route traffic to the Realtime Engine, the service worker appends a Spec-managed domain to the incoming host value, for example:

  • www.client.com.spec-domain.com

note

The appended hostname will be provided upon integration, and is useful in validating the Spec health check endpoint:

  • www.client.com.spec-domain.com/example/healthz

Mirror Mode

  • inlineMode is set to false

In mirror mode, the service worker receives each incoming request and constructs a copy using a provider-specific request constructor. This copied request is sent in the background to Spec servers, which return a 200 OK response. Meanwhile, the original request proceeds to your origin server without delay. The Realtime Engine only sees the request, not the response.

  • Non-blocking behavior: The service worker does not wait for a response from Spec before forwarding the request.
  • Resilient fallback: If Spec is unavailable, traffic to your origin continues unaffected.
  • No caching: Spec responses include Cache-Control: no-store to avoid caching the 200 OK that is generated from the backgrounded worker request.
    • This ensures a mirror response is never cached by the CDN or worker.

This mode enables Spec to:

  • Identify fraudulent activity
  • Apply labels
  • Trigger asynchronous workflows (e.g., alerting your team to events)

warning

Mirror mode does not allow Spec to block or alter traffic in real time.

Active (Inline) Mode

  • inlineMode is set to true

Active mode includes both Active Inline and Pass Through realtime processing modes. In all inline modes, the original network traffic is routed to Spec servers from the edge service worker, then to your origin servers. To understand how each option functions, take a look at our processing modes page. Spec removes the appended Spec-managed domain from the request and reconstructs the request to forward to an origin server. The Realtime Engine will be able to see the request and response from your origin.

  • Connection efficiency: Keep-alive settings improve performance by reusing TCP connections, minimizing the overhead of repeated connection setup.
  • Intelligent fallback: If Spec servers are unreachable (via DNS health check), traffic is rerouted through a secondary Spec-managed worker that strips the appended domain and forwards requests to your origin using a mapping value.
  • Custom error handling: You may opt to disable fallback routing and instead serve a custom error page or response.

Inline mode retains all the benefits of mirror, with the added ability to:

  • Execute synchronous workflows
  • Actively block malicious requests and prevent bad actors from reaching your origin
  • View response data, analyze outcomes, and take appropriate actions based on results.

Check out the page for Inline Networking for more information on our flexible routing options.

important

We recommend starting in Mirror mode during initial integration. This allows Spec to gather behavioral data, identify trends, and verify signal quality before transitioning to Active Inline mode for realtime enforcement.

Why Service Workers?

Service workers process data near users, reducing latency and enhancing realtime performance while optimizing bandwidth and improving security. Spec uses edge computing to route traffic from a CDN to Spec's Realtime Engine. It can either duplicate requests to Spec while sending the original to the origin server ("pass-through" mode) or forward requests directly to Spec, who in turn forwards requests to the origin server ("active" mode).

To learn more about the HTTP library's functionality, explore the source here: