npm package: @queue-it/fastly
Description: Queue-it connector for Fastly
Author: devs@queue-it.com
Latest version: 4.4.3

# KnownUser.V3.Fastly

The Queue-it Security Framework ensures that end-users are not able to access your online application without first
going through the queue for any and all `protected` areas and paths on your sites. The queue system is implemented by
adding a server-side (request-level) integration that protects your online application by redirecting users to a waiting
room according to web traffic settings in the Queue-it GO Platform. After the integration is complete, queue system
behavior and operations are managed in Queue-it's Go Platform and/or via the Queue-it Admin API.

This Fastly Queue-it Connector SDK (aka, Queue-it's server-side KnownUser connector) uses a Compute@Edge service to
integrate Queue-it's functionality into Fastly's network.

A Wasm service is required to utilize this connector.

> You can find the latest released version [here](https://github.com/queueit/KnownUser.V3.Fastly/releases/latest).

## Introduction

When a user makes a request to your Fastly service our connector validates the request and if it is needed, it will
redirect the user to the waiting room. After waiting in the waiting room, the queue engine will redirect the user back
to your end attaching a query string parameter ( `queueittoken` ) containing some information about the user to the URL.
The most important fields of the `queueittoken` are:

- q - The user's unique queue identifier
- ts - A timestamp of how long this redirect is valid
- h - A hash of the token

After the user returns from the queue, the connector will let the user continue his request to your backend ( without
redirecting to the queue since the request has a valid queueittoken as query string) .

## Installation

There are two methods of installation:

### As a standalone service

- Go to the Fastly services page and create a new **Wasm** service.
- Go to Domains and fill in the domain that you want your service to be reachable at. You may need to register a CNAME
  record if you have your own domain.
- Then click on *Origins* and add a new host that has the hostname of your origin server.  
  You need to edit the Host and name it **origin**.
- Create a second host that has the hostname of `{yourCustomerId}.queue-it.net` and name it **queue-it**.  
  Edit the host, go to advanced options and fill in the same hostname in **Override host**
- Go to **Resources -> Config stores** and create a new config store named `IntegrationConfiguration`.
  - Add the following items in the config store (you can find these values in the Go Queue-It self-service platform):
    - customerId: Your customer ID
    - apiKey: The API key for your account
    - secret: Your KnownUserV3 secret
    - queueItOrigin: The name of the queue-it host, in this case it's `queue-it`  
  - Go to **Linked Services** and click on `Link Service`
    - Select your service and click `Next`
    - Click `Link and activate` to link the `Config store` to your service. It should generate a new version
  - You can verify that the `Config store` has been linked by going to your service and see it in the section `Config stores`
- Download the latest package from the releases page and unarchive it.
- Edit the `fastly.toml` file and copy the ID of your service (you can see this by opening up the service in Fastly) and
  replace **{YourServiceId}** with it.
- Archive the directory in the same format (tar.gz).
- Go to `Package` in the Fastly service page and upload the package.
- To finish up and deploy your service click on the **Activate** button.

### Customizable service with the connector

- Go to the Fastly services page and create a new **Wasm** service and copy it's ID.
- Clone this repository and edit the fastly.toml file, make sure to set the `service_id` field to the ID you copied.
- Then click on *Origins* and add a new host that has the hostname of your origin server.
  You can name the host **origin** or whatever you choose.
- Create a host that has the hostname of `{yourCustomerId}.queue-it.net` and name it **queue-it**.
  Edit the host, go to advanced options and fill in the same hostname in **Override host**
- Go to **Resources -> Config stores** and create a new config store named `IntegrationConfiguration`.
  - Add the following items in the config store (you can find these values in the Go Queue-It self-service platform):
    - customerId: Your customer ID
    - apiKey: The API key for your account
    - secret: Your KnownUserV3 secret
    - queueItOrigin: The name of the queue-it host, in this case it's `queue-it`
  - Go to **Linked Services** and click on `Link Service`
    - Select your service and click `Next`
    - Click `Link and activate` to link the `Config store` to your service. It should generate a new version
  - You can verify that the `Config store` has been linked by going to your service and see it in the section `Config stores`
- You need to add some code that uses this connector. Here is an example:

```ts
import {Fastly} from "@fastly/as-compute";
import {onQueueITRequest, IntegrationDetails, onQueueITResponse} from "@queue-it/fastly";

const req = Fastly.getClientRequest();

// This is optional and can be null if it's specified in your Config Store
const integrationDetails = new IntegrationDetails(
        "QueueItOriginName",
        "CustomerId",
        "SecretKey",
        "ApiKey");
let res = onQueueITRequest(req, integrationDetails);

if (res != null) {
    Fastly.respondWith(res!);
} else {
    const myOrigin = 'Ticketania';
    const cacheOverride = new Fastly.CacheOverride();
    const res = Fastly.fetch(req, {
        backend: myOrigin,
        cacheOverride,
    }).wait();
    onQueueITResponse(res);
    Fastly.respondWith(res);
} 
```

- Build and deploy the package running `fastly compute build` and `fastly compute deploy` in the same directory.
- Create desired waiting room(s), triggers, and actions in the Go Queue-It self-service platform.  
  Then, save/publish the configuration.

## Enqueue Token Settings

The connector supports enqueue tokens, which are used to secure the queue redirect flow. These settings are read at runtime from the Fastly `IntegrationConfiguration` Config Store. They are optional — if not set, the defaults below apply.

| Key | Default | Description |
|-----|---------|-------------|
| `enqueueTokenEnabled` | `"true"` | Enables enqueue token generation. Set to `"false"` to disable. |
| `enqueueTokenValidityTime` | `"240000"` | Token validity time in milliseconds. |
| `enqueueTokenKeyEnabled` | `"false"` | Enables key-based enqueue tokens. Set to `"true"` to enable. |

To configure these, add them as items in the `IntegrationConfiguration` Config Store alongside the other settings (`customerId`, `apiKey`, `secret`, etc.) — either via the Fastly UI or the Fastly API.

## Request Body Trigger Matching

The connector supports matching triggers based on the request body content. This is disabled by default. When enabled, up to 2048 characters of the request body are read and passed to the SDK for trigger evaluation.

To enable it, add the following key to the `IntegrationConfiguration` Config Store:

| Key | Default | Description |
|-----|---------|-------------|
| `requestBodyEnabled` | `"false"` | Set to `"true"` to enable request body trigger matching. |

## Providing the queue configuration

The recommended way is to use the Go Queue-it self-service portal to setup the configuration. The configuration
specifies a set of Triggers and Actions. A Trigger is an expression matching one, more or all URLs on your website. When
a user enter your website and the URL matches a Trigger-expression the corresponding Action will be triggered. The
Action specifies which waiting room the users should be send to. In this way you can specify which waiting room(s)
should protect which page(s) on the fly without changing the server-side integration.

## Protecting AJAX calls

If you need to protect AJAX calls beside page loads you need to add the below JavaScript tags to your pages:

```html

<script type="text/javascript" src="//static.queue-it.net/script/queueclient.min.js"></script>
<script
        data-queueit-intercept-domain="{YOUR_CURRENT_DOMAIN}"
        data-queueit-intercept="true"
        data-queueit-c="{YOUR_CUSTOMER_ID}"
        type="text/javascript"
        src="//static.queue-it.net/script/queueconfigloader.min.js">
</script>
```