@queue-it/fastly 4.4.3 → 5.0.0-beta.1

package/README.md

@@ -1,156 +1,4 @@
-# KnownUser.V3.Fastly
+# Queue-it Connector for 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.
+The package enables you to add traffic management support to your website. The Connector Implementation Guide can be found via the Queue-it GO Platform | Help | Connector Integration Documentation. In order to get access please reach out to your Queue-it representative.
 
-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>
-```

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@queue-it/fastly",
-  "version": "4.4.3",
+  "version": "5.0.0-beta.1",
   "description": "Queue-it connector for Fastly",
   "main": "src/index.ts",
   "author": "devs@queue-it.com",
-  "repository": "https://github.com/queueit/KnownUser.V3.Fastly",
+  "repository": "https://github.com/queueit/connector-fastly",
   "license": "MIT",
   "files": [
     "package.json",
     "README.md",
     "src/helpers",
     "src/fastlyCryptoProvider.ts",
+    "src/fastlyDirectActionProvider.ts",
     "src/contextProvider.ts",
     "src/helper.ts",
     "src/integrationConfigProvider.ts",
@@ -25,7 +26,7 @@
   },
   "dependencies": {
     "@fastly/js-compute": "^3.0.0",
-    "@queue-it/connector-javascript": "^4.4.4",
+    "@queue-it/connector-javascript": "~5.0.1",
     "@queue-it/queue-token": "~1.0.4"
   },
   "devDependencies": {

package/src/contextProvider.ts

@@ -2,6 +2,7 @@ import {
     DefaultEnqueueTokenProvider,
     IConnectorContextProvider,
     ICryptoProvider,
+    IDirectActionProvider,
     IEnqueueTokenProvider,
     INormalizationProvider,
     DefaultNormalizationProvider,
@@ -10,9 +11,15 @@ import {
 } from '@queue-it/connector-javascript';
 import { Token, Payload } from '@queue-it/queue-token';
 import { FastlyCryptoProvider } from './fastlyCryptoProvider';
-
-export function getHttpHandler(req: Request, clientIp: string = '', bodyString: string = ''): FastlyHttpContextProvider {
-    return new FastlyHttpContextProvider(req, clientIp, bodyString);
+import { FastlyDirectActionProvider, FastlyDirectActionsSettings } from './fastlyDirectActionProvider';
+
+export function getHttpHandler(
+    req: Request,
+    clientIp: string = '',
+    bodyString: string = '',
+    directActionsSettings?: FastlyDirectActionsSettings
+): FastlyHttpContextProvider {
+    return new FastlyHttpContextProvider(req, clientIp, bodyString, directActionsSettings);
 }
 
 export class FastlyHttpContextProvider implements IConnectorContextProvider {
@@ -22,12 +29,23 @@ export class FastlyHttpContextProvider implements IConnectorContextProvider {
     private _enqueueTokenProvider: IEnqueueTokenProvider | null = null;
     private readonly _normalizationProvider: INormalizationProvider;
     private readonly _cryptoProvider: ICryptoProvider;
-
-    constructor(fReq: Request, clientIp: string = '', bodyString: string = '') {
+    private readonly _directActionProvider: IDirectActionProvider;
+
+    constructor(
+        fReq: Request,
+        clientIp: string = '',
+        bodyString: string = '',
+        directActionsSettings?: FastlyDirectActionsSettings
+    ) {
         this._httpRequest = new FastlyHttpRequest(fReq, clientIp, bodyString);
         this._httpResponse = new FastlyHttpResponse();
         this._normalizationProvider = new DefaultNormalizationProvider();
         this._cryptoProvider = new FastlyCryptoProvider();
+        this._directActionProvider = new FastlyDirectActionProvider(
+            this._httpRequest,
+            this._httpResponse,
+            directActionsSettings
+        );
     }
 
     getHttpRequest(): IHttpRequest {
@@ -72,6 +90,10 @@ export class FastlyHttpContextProvider implements IConnectorContextProvider {
         return this._normalizationProvider;
     }
 
+    getDirectActionProvider(): IDirectActionProvider {
+        return this._directActionProvider;
+    }
+
     getResponseHeaders(): Headers {
         return this._httpResponse.getHeaders();
     }

package/src/fastlyDirectActionProvider.ts

@@ -0,0 +1,137 @@
+import {
+  IDebugService,
+  IDirectActionProvider,
+  IDirectActionSettings,
+  IDirectPassRequestDTO,
+  IDirectPassResponseDTO,
+  IDirectPassResult,
+  IHttpRequest,
+  IHttpResponse,
+} from "@queue-it/connector-javascript";
+import { PLATFORM_VERSION } from "./helper";
+
+export interface FastlyDirectActionsSettings {
+  disabled: boolean;
+  proxyKey: string | null;
+  directPassTimeoutMillis?: number;
+  isTestEnvironment?: boolean;
+  // Fastly backend name used to reach `*.queue-it.net`. Reuses the same backend
+  // as the integration config fetch so no extra backend setup is required.
+  queueItOrigin?: string;
+}
+
+export class FastlyDirectActionProvider implements IDirectActionProvider {
+  private _settings: IDirectActionSettings;
+  private _isTestEnvironment: boolean;
+  private _backend?: string;
+
+  constructor(
+    protected httpRequest: IHttpRequest,
+    protected httpResponse: IHttpResponse,
+    protected settings?: FastlyDirectActionsSettings
+  ) {
+    this._settings = {
+      disabled: settings?.disabled === true,
+      proxyKey: settings?.proxyKey ?? "",
+      directPass: {
+        timeoutMillis: settings?.directPassTimeoutMillis,
+      },
+    };
+    this._isTestEnvironment = settings?.isTestEnvironment === true;
+    this._backend = settings?.queueItOrigin;
+  }
+
+  getSettings(): IDirectActionSettings {
+    return this._settings;
+  }
+
+  async tryDirectPass(
+    customerId: string,
+    waitingRoomId: string,
+    actionName: string,
+    protectedUrl: string,
+    proxyKey: string,
+    clientIp: string,
+    userAgent: string,
+    referer: string,
+    timeout: number,
+    sdkVersion: string,
+    debugService: IDebugService
+  ): Promise<IDirectPassResult> {
+    const requestDto: IDirectPassRequestDTO = {
+      protectedUrl,
+      connectorPlatformVersion: PLATFORM_VERSION,
+      sdkVersion,
+      actionName,
+    };
+
+    const requestBody = JSON.stringify(requestDto);
+    const envSuffix = this._isTestEnvironment ? ".test" : "";
+    const url = `https://${customerId}${envSuffix}.queue-it.net/front-door/api/${customerId}/waiting-rooms/${waitingRoomId}/try-pass`;
+
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+    try {
+      const fetchInit: RequestInit & { backend?: string; cacheOverride?: CacheOverride } = {
+        method: "POST",
+        body: requestBody,
+        headers: {
+          "Accept": "application/json",
+          "Content-Type": "application/json",
+          "User-Agent": userAgent,
+          "Referer": referer,
+          "x-queueit-proxykey": proxyKey,
+          "x-queueit-clientip-yb85x": clientIp,
+        },
+        cacheOverride: new CacheOverride("pass"),
+      };
+      if (this._backend) {
+        fetchInit.backend = this._backend;
+      }
+
+      // Fastly Compute does not expose AbortController; per Fastly's "set a timeout
+      // on a request" example we race the fetch against a setTimeout. The in-flight
+      // request keeps running in the background until the backend's first_byte_timeout
+      // kills it.
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(new Error(`Direct pass timeout after ${timeout}ms`)),
+          timeout
+        );
+      });
+      const response = await Promise.race([fetch(url, fetchInit), timeoutPromise]);
+
+      if (debugService.isConnectorDiagnosticEnabled()) {
+        debugService.addDebugEntry("DirectActionHttpReponseCode", response.status.toString());
+      }
+
+      if (!response.ok) {
+        if (response.status >= 500) {
+          throw new Error(`Try pass did not receive proper response. Status: ${response.status}`);
+        }
+        return { hasPassed: false };
+      }
+
+      const responseBody: IDirectPassResponseDTO = await response.json();
+
+      if (debugService.isConnectorDiagnosticEnabled()) {
+        debugService.addDebugEntry(
+          "DirectActionHttpResponseBody",
+          `HasPassed:${responseBody.HasPassed}&QueueItToken:${responseBody.QueueItToken}`
+        );
+      }
+
+      if (!responseBody || !Object.prototype.hasOwnProperty.call(responseBody, "HasPassed")) {
+        return { hasPassed: false };
+      }
+
+      return { hasPassed: responseBody.HasPassed, queueitToken: responseBody.QueueItToken };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : JSON.stringify(err);
+      console.error(`Direct pass error: ${message}`);
+      throw err;
+    } finally {
+      if (timeoutId !== null) clearTimeout(timeoutId);
+    }
+  }
+}

package/src/helper.ts

@@ -1,11 +1,13 @@
 export class QueueITHelper {
-  static readonly KUP_VERSION: string = "fastly-4.4.3";
+  static readonly KUP_VERSION: string = "fastly-5.0.0";
 
   static addKUPlatformVersion(redirectQueueUrl: string): string {
-    return redirectQueueUrl + "&kupver=" + QueueITHelper.KUP_VERSION;
+    return `${redirectQueueUrl}&kupver=${QueueITHelper.KUP_VERSION}`;
   }
 }
 
+export const PLATFORM_VERSION = QueueITHelper.KUP_VERSION;
+
 export interface RequestLogger {
   log(message: string): void;
 }

package/src/index.ts

@@ -1,3 +1,5 @@
 export {IntegrationDetails, EnqueueTokenProviderFactory, IntegrationEndpointProvider, IntegrationEndpointCacheConfig, resolveIntegrationDetails} from "./integrationConfigProvider"
 export {onQueueITRequest, onQueueITResponse} from "./requestResponseHandler";
 export {RequestLogger} from "./helper";
+export {FastlyDirectActionProvider} from "./fastlyDirectActionProvider";
+export type {FastlyDirectActionsSettings} from "./fastlyDirectActionProvider";

package/src/integrationConfigProvider.ts

@@ -1,6 +1,7 @@
 import { ConfigStore } from "fastly:config-store";
 import { IEnqueueTokenProvider } from "@queue-it/connector-javascript";
 import { RequestLogger } from "./helper";
+import { FastlyDirectActionsSettings } from "./fastlyDirectActionProvider";
 
 export type EnqueueTokenProviderFactory = (
   customerId: string,
@@ -59,7 +60,11 @@ const integrationCustomerId = "customerId",
   enqueueTokenEnabledKey = "enqueueTokenEnabled",
   enqueueTokenValidityTimeKey = "enqueueTokenValidityTime",
   enqueueTokenKeyEnabledKey = "enqueueTokenKeyEnabled",
-  requestBodyEnabledKey = "requestBodyEnabled";
+  requestBodyEnabledKey = "requestBodyEnabled",
+  directActionsDisabledKey = "directActionsDisabled",
+  directActionsProxyKeyKey = "directActionsProxyKey",
+  directPassTimeoutKey = "directPassTimeout",
+  isTestEnvironmentKey = "isTestEnvironment";
 
 export function resolveIntegrationDetails(): IntegrationDetails | null {
   const dict = new ConfigStore(integrationDictionary);
@@ -102,8 +107,41 @@ export function resolveIntegrationDetails(): IntegrationDetails | null {
     requestBodyEnabled = requestBodyEnabledVal.toLowerCase() === "true";
   }
 
+  let directActionsDisabled = false;
+  const directActionsDisabledVal = dict.get(directActionsDisabledKey);
+  if (directActionsDisabledVal !== null) {
+    directActionsDisabled = directActionsDisabledVal.toLowerCase() === "true";
+  }
+
+  const directActionsProxyKeyVal = dict.get(directActionsProxyKeyKey);
+  const directActionsProxyKey: string | null =
+    directActionsProxyKeyVal && directActionsProxyKeyVal.length > 0
+      ? directActionsProxyKeyVal
+      : null;
+
+  let directPassTimeoutMillis: number | undefined;
+  const directPassTimeoutVal = dict.get(directPassTimeoutKey);
+  if (directPassTimeoutVal !== null) {
+    const parsed = parseInt(directPassTimeoutVal, 10);
+    if (!Number.isNaN(parsed)) directPassTimeoutMillis = parsed;
+  }
+
+  let isTestEnvironment = false;
+  const isTestEnvironmentVal = dict.get(isTestEnvironmentKey);
+  if (isTestEnvironmentVal !== null) {
+    isTestEnvironment = isTestEnvironmentVal.toLowerCase() === "true";
+  }
+
+  if (!directActionsDisabled && !directActionsProxyKey) {
+    throw new Error(
+      "Direct Actions are enabled but no proxy key is provided. Set directActionsDisabled to true to disable, or provide directActionsProxyKey."
+    );
+  }
+
+  const queueItOrigin = dict.get(integrationQueueItOrigin)!;
+
   return new IntegrationDetails(
-    dict.get(integrationQueueItOrigin)!,
+    queueItOrigin,
     dict.get(integrationCustomerId)!,
     dict.get(integrationSecret)!,
     dict.get(integrationApiKey)!,
@@ -111,7 +149,16 @@ export function resolveIntegrationDetails(): IntegrationDetails | null {
     enqueueTokenEnabled,
     enqueueTokenValidityTime,
     enqueueTokenKeyEnabled,
-    requestBodyEnabled
+    requestBodyEnabled,
+    new QueueItIntegrationEndpointProvider(),
+    new MockLogger(),
+    {
+      disabled: directActionsDisabled,
+      proxyKey: directActionsProxyKey,
+      directPassTimeoutMillis,
+      isTestEnvironment,
+      queueItOrigin,
+    }
   );
 }
 
@@ -168,6 +215,8 @@ export class IntegrationDetails {
    */
   public clientIp: string = '';
 
+  public directActionsSettings: FastlyDirectActionsSettings;
+
   constructor(
     public queueItOrigin: string,
     public customerId: string,
@@ -179,8 +228,15 @@ export class IntegrationDetails {
     public enqueueTokenKeyEnabled: boolean = false,
     public requestBodyEnabled: boolean = false,
     public provider: IntegrationEndpointProvider = new QueueItIntegrationEndpointProvider(),
-    public logger: RequestLogger = new MockLogger()
-  ) {}
+    public logger: RequestLogger = new MockLogger(),
+    directActionsSettings?: FastlyDirectActionsSettings
+  ) {
+    this.directActionsSettings = directActionsSettings ?? {
+      disabled: false,
+      proxyKey: null,
+      queueItOrigin,
+    };
+  }
 
   resolveWorkerRequestUrl(pureUrl: string): string {
     if (this.workerHost == "") {

package/src/requestResponseHandler.ts

@@ -38,7 +38,7 @@ export async function onQueueITRequest(
     bodyString = ((await req.clone().text()) || '').substring(0, 2048);
   }
 
-  httpProvider = getHttpHandler(req, conf.clientIp, bodyString);
+  httpProvider = getHttpHandler(req, conf.clientIp, bodyString, conf.directActionsSettings);
   sendNoCacheHeaders = false;
 
   if (conf.enqueueTokenEnabled) {