Fallback endpoint support (#92)

* Fallback endpoint support WIP

* Try the fallback endpoints in a specific order

* Handle paths better for retries

* Add global fallbacks

* Update test expectation

* Add changelog entry

* Fix changelog entries

Author: gzuidhof

CHANGELOG.md

@@ -1,5 +1,8 @@
 # changelog
 
+## 0.2.3
+- Support for fallback endpoints (for retrying with a different endpoint when the primary one is unreachable).
+
 ## 0.2.2
 - Fix `startMode: "focus"` not working if the widget is mounted under a shadow root (e.g. in a web component).
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@friendlycaptcha/sdk",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "In-browser SDK for Friendly Captcha v2",
   "main": "dist/sdk.js",
   "exports": {

package.json

@@ -0,0 +1,10 @@
+<main>
+    <form>
+        <input type="textarea" />
+        <div class="frc-captcha" data-sitekey="{{ .Config.Sitekey }}" data-api-endpoint="https://doesntexistfrc.com,{{ .Config.APIEndpoint }}"></div>
+        <input type="submit" />
+    </form>
+</main>
+
+<script defer src="{{ .SiteJSPath }}"></script>
+<script defer src="main.tmpl.ts"></script>

sdktest/test/fallback_endpoint/body.tmpl.html

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Friendly Captcha GmbH 2023.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { sdktest } from "../../sdktestlib/sdk.js";
+
+sdktest.description("The widget has an invalid endpoint, but a fallback endpoint is configured, so the widget should complete successfully.");
+
+sdktest.test({ name: "one widget present" }, async (t) => {
+  t.require.numberOfWidgets(1);
+});
+
+sdktest.test({ name: "widget completes after focusing form" }, async (t) => {
+
+  const w = t.getWidget()!;
+  const completePromise = t.assert.widgetCompletes(w)
+
+  const ta: HTMLTextAreaElement = document.querySelector("input[type=\"textarea\"]")!;
+  ta.focus();
+
+  await completePromise
+});
+

sdktest/test/fallback_endpoint/main.tmpl.ts

@@ -0,0 +1,6 @@
+<main>
+    <div class="frc-captcha" data-sitekey="{{ .Config.Sitekey }}" data-api-endpoint="https://invalid-a.example.invalid,https://invalid-b.example.invalid,https://invalid-c.example.invalid,https://invalid-d.example.invalid"></div>
+</main>
+
+<script defer src="{{ .SiteJSPath }}"></script>
+<script defer src="main.tmpl.ts"></script>

sdktest/test/many_invalid_endpoints/body.tmpl.html

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Friendly Captcha GmbH 2023.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { sdktest } from "../../sdktestlib/sdk.js";
+
+sdktest.description("Widget uses a CSV list of invalid API endpoints and should end in an unreachable network error.");
+
+sdktest.test({ name: "one widget present" }, async (t) => {
+  t.require.numberOfWidgets(1);
+});
+
+sdktest.test({ name: "widget errors as unreachable" }, async (t) => {
+  const w = t.getWidget()!;
+
+  const errorPromise = t.assert.widgetErrors(w);
+  t.startAllWidgets();
+
+  const evtData = await errorPromise;
+  t.assert.truthy(evtData.response.startsWith(".ERROR.UNREACHABLE"));
+  t.assert.equal("error", evtData.state);
+  t.assert.equal("network_error", evtData.error.code);
+});

sdktest/test/many_invalid_endpoints/main.tmpl.ts

@@ -25,7 +25,7 @@ export class CommunicationBus {
    */
   origins: Set<string> = new Set();
 
-  // We use a map here to prevent the need to add a Map polyfill in the widget.
+  // We use a Record here to prevent the need to add a Map polyfill in the widget.
   targets: Record<string, CommunicationTarget> = {};
 
   /** Some messages that expect an answer may be handled twice if two SDKs are present. Here we keep track of those and deliver them only once. */
@@ -57,11 +57,11 @@ export class CommunicationBus {
   }
 
   /**
-   * Add an origin to allow messages from.
+   * Add origins to allow messages from.
    * @internal
    */
-  public addOrigin(origin: string) {
-    this.origins.add(origin);
+  public addOrigins(origins: string[]) {
+    origins.forEach((origin) => this.origins.add(origin));
   }
 
   /**

src/communication/bus.ts

@@ -6,20 +6,38 @@
  */
 import { originOf } from "../util/url.js";
 
+
+
+const toFRCAPIUrl = (hosts: string[]) => hosts.map((h) => `https://${h}.frcapi.com`).join(",");
+
 const SHORTHANDS: Record<string, string> = {
-  eu: "https://eu.frcapi.com",
-  global: "https://global.frcapi.com",
+  eu: toFRCAPIUrl(["eu", "eu0", "eu1"]),
+  global: toFRCAPIUrl(["global", "global0", "global1"]),
 };
 
-export function resolveAPIOrigin(optionValue: string | undefined) {
-  let v = optionValue;
-  if (!v) {
-    // We default to the global endpoint
-    v = SHORTHANDS.global;
-  } else if (SHORTHANDS[v]) {
-    v = SHORTHANDS[v];
+const splitCSV = (value: string) => value.split(",").map((v) => v.trim()).filter((v) => !!v);
+
+const expandEndpointShorthand = (value: string) => splitCSV(SHORTHANDS[value] || value);
+
+/**
+ * resolveAPIOrigin resolves the value of the API origin to use for the SDK.
+ * If no value is specified, it defaults to the "global" shorthand. The "eu" and "global" shorthands are expanded to multiple endpoints for redundancy. Custom URLs are used as-is.
+ * @param optionValue The value of the API origin to use for the SDK.
+ * @returns A list of API origins to use for the SDK, with shorthands expanded.
+ */
+export function resolveAPIOrigins(optionValue: string | undefined): string[] {
+  const endpointList = optionValue || SHORTHANDS.global;
+  const resolved = splitCSV(endpointList)
+    .reduce((acc: string[], endpoint) => acc.concat(expandEndpointShorthand(endpoint)), [])
+    .map(originOf);
+
+  if (resolved.length > 0) {
+    return resolved;
   }
-  return originOf(v);
+
+  // If the endpoint string was provided but resolved to nothing (e.g. ", ,"),
+  // fall back to the default global endpoint instead of returning an empty list.
+  return splitCSV(SHORTHANDS.global).map(originOf);
 }
 
 export function getSDKDisableEvalPatching(): boolean {

src/sdk/options.ts

@@ -0,0 +1,84 @@
+/*!
+ * Copyright (c) Friendly Captcha GmbH 2023.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { shuffledCopy } from "../util/random.js";
+import { originOf } from "../util/url.js";
+import { stringHasPrefix } from "../util/string.js";
+
+/**
+ * Build a retry origin list with these rules:
+ * 1) The first entry is the primary origin (origins[0]).
+ * 2) Remaining entries are fallback origins (origins[1..]) in shuffled order.
+ *
+ * Example:
+ * origins = ["https://0.example.com", "https://1.example.com", "https://2.example.com", "https://3.example.com"]
+ * shuffled fallbacks (example) = ["https://2.example.com", "https://3.example.com", "https://1.example.com"]
+ * output origins = [
+ *   "https://0.example.com",
+ *   "https://2.example.com",
+ *   "https://3.example.com",
+ *   "https://1.example.com"
+ * ]
+ * 
+ * @private
+ */
+export function getRetryOrigins(origins: string[]): string[] {
+  if (origins.length === 0) return [];
+  return [origins[0]].concat(shuffledCopy(origins.slice(1)));
+}
+
+/**
+ * Returns the index in retryOrigins to use for a given attempt number.
+ *
+ * - Attempts 0, 1, and 2 map to index 0 (primary).
+ * - Following attempts map to fallback indices in order.
+ * - If attempts exceed unique fallbacks, a random fallback index is used.
+ * 
+ * @private
+ */
+export function getRetryOriginIndex(
+  attemptNumber: number,
+  retryOrigins: string[],
+): number {
+  const retryOriginsLength = retryOrigins.length;
+  if (retryOriginsLength === 0) return -1;
+  // We intentionally map attempt 0 to primary as a bug-tolerant fallback.
+  if (attemptNumber <= 2 || retryOriginsLength === 1) return 0;
+
+  const fallbackCount = retryOriginsLength - 1;
+  const fallbackAttempt = attemptNumber - 2;
+  if (fallbackAttempt <= fallbackCount) {
+    return fallbackAttempt;
+  }
+
+  return 1 + Math.floor(Math.random() * fallbackCount);
+}
+
+/**
+ * Builds a retry URL by replacing the source origin with `nextOrigin` and
+ * appending a `retry=<n>` query parameter.
+ *
+ * - Supports absolute and relative `src` values.
+ * - Normalizes `nextOrigin` to its origin (ignoring trailing slashes/paths).
+ * - Assumes `src` does not contain a URL fragment (`#...`).
+ *
+ * @private
+ */
+export function getRetrySrc(src: string, nextOrigin: string, retryCount: number): string {
+  const srcOrigin = originOf(src);
+  const normalizedNextOrigin = originOf(nextOrigin);
+
+  let pathAndQuery = stringHasPrefix(src, srcOrigin) ? src.slice(srcOrigin.length) : src;
+  if (pathAndQuery.length === 0) {
+    pathAndQuery = "/";
+  } else if (!stringHasPrefix(pathAndQuery, "/")) {
+    pathAndQuery = "/" + pathAndQuery;
+  }
+
+  const separator = pathAndQuery.indexOf("?") === -1 ? "?" : "&";
+  return normalizedNextOrigin + pathAndQuery + separator + "retry=" + retryCount;
+}