feat(lib): route Automate, App Automate, Accessibility and Observability to the account's GRR region

src/lib/account-region.ts

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import logger from "../logger.js";
+import { BrowserStackConfig } from "./types.js";
+import { fetchTokenTransport, mintCentralToken } from "./central-oauth.js";
+import { AccountRegion, GRR_REGIONS, GrrRegion } from "./region-context.js";
+
+const AUTH_TOKEN_URL = "https://auth.browserstack.com/oauth2/v2/token";
+const SCOPE = "oauth_user_profile";
+const LOOKUP_TIMEOUT_MS = 5_000;
+/** How long a failed lookup answers "unknown" before the next call tries again. */
+export const RETRY_AFTER_MS = 5_000;
+/** How long a looked-up region is reused before it is looked up again. */
+export const REGION_TTL_MS = 60 * 60_000;
+const MAX_ENTRIES = 1_000;
+
+interface Lookup {
+  settled?: AccountRegion;
+  settledAt?: number;
+  pending?: Promise<AccountRegion>;
+  failedAt?: number;
+}
+
+// Keyed on a hash of the credentials, so servers built per request for the same account
+// share one lookup. Holds only the region; bounded, oldest entry evicted first.
+const lookups = new Map<string, Lookup>();
+
+function keyFor(config: BrowserStackConfig): string {
+  return createHash("sha256")
+    .update(
+      `${config["browserstack-username"]}\0${config["browserstack-access-key"]}`,
+    )
+    .digest("hex");
+}
+
+function remember(key: string, entry: Lookup): void {
+  lookups.delete(key);
+  lookups.set(key, entry);
+  if (lookups.size > MAX_ENTRIES) {
+    lookups.delete(lookups.keys().next().value!);
+  }
+}
+
+/** Reads `user.grr.region` from the token; an account with no region is a US account. */
+export function regionFromToken(token: string): AccountRegion {
+  const payload = JSON.parse(
+    Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"),
+  );
+  const raw = payload?.user?.grr?.region;
+  if (raw === undefined || raw === null || raw === "") return "us";
+  const region = String(raw).toLowerCase();
+  return (GRR_REGIONS as readonly string[]).includes(region)
+    ? (region as GrrRegion)
+    : "unknown";
+}
+
+/** The account's region from BrowserStack auth, or null when auth names none we know. */
+async function lookUp(config: BrowserStackConfig): Promise<GrrRegion | null> {
+  try {
+    const token = await mintCentralToken({
+      url: AUTH_TOKEN_URL,
+      scope: SCOPE,
+      credentials: {
+        username: config["browserstack-username"],
+        accessKey: config["browserstack-access-key"],
+      },
+      transport: fetchTokenTransport(LOOKUP_TIMEOUT_MS),
+      refreshSkewMs: 0,
+      cacheEnabled: false,
+    });
+    const region = regionFromToken(token);
+    return region === "unknown" ? null : region;
+  } catch (error) {
+    logger.warn(
+      `Could not look up the account's region: ${(error as Error)?.message}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * The account's region, looked up once per account and refreshed after REGION_TTL_MS.
+ * Returned directly once known, so a known region costs a call no wait; undefined without
+ * credentials. A refresh keeps answering the last known region, and keeps it if the
+ * refresh fails. With no region known, a failure answers "unknown" for RETRY_AFTER_MS,
+ * and the next call after that looks up again.
+ */
+export function accountRegion(
+  config: BrowserStackConfig | undefined,
+): AccountRegion | undefined | Promise<AccountRegion> {
+  if (
+    !config?.["browserstack-username"] ||
+    !config?.["browserstack-access-key"]
+  ) {
+    return undefined;
+  }
+  const now = Date.now();
+  const key = keyFor(config);
+  const lookup = lookups.get(key);
+  if (lookup?.settled && now - lookup.settledAt! < REGION_TTL_MS) {
+    return lookup.settled;
+  }
+  if (lookup?.pending) return lookup.settled ?? lookup.pending;
+  if (
+    lookup?.failedAt !== undefined &&
+    now - lookup.failedAt < RETRY_AFTER_MS
+  ) {
+    return lookup.settled ?? "unknown";
+  }
+
+  const entry: Lookup = {
+    settled: lookup?.settled,
+    settledAt: lookup?.settledAt,
+  };
+  entry.pending = lookUp(config).then((region) => {
+    entry.pending = undefined;
+    if (region === null) {
+      entry.failedAt = Date.now();
+      return entry.settled ?? "unknown";
+    }
+    entry.settled = region;
+    entry.settledAt = Date.now();
+    entry.failedAt = undefined;
+    return region;
+  });
+  remember(key, entry);
+  return entry.settled ?? entry.pending;
+}

src/lib/api.ts

@@ -1,13 +1,15 @@
 import { getBrowserStackAuth } from "./get-auth.js";
 import { BrowserStackConfig } from "../lib/types.js";
 import { apiClient } from "./apiClient.js";
+import { getRegionalHost } from "./regional-host.js";
 
 export async function getLatestO11YBuildInfo(
   buildName: string,
   projectName: string,
   config: BrowserStackConfig,
 ) {
-  const buildsUrl = `https://api-observability.browserstack.com/ext/v1/builds/latest?build_name=${encodeURIComponent(
+  const host = getRegionalHost("observabilityApi");
+  const buildsUrl = `${host}/ext/v1/builds/latest?build_name=${encodeURIComponent(
     buildName,
   )}&project_name=${encodeURIComponent(projectName)}`;
 

src/lib/region-context.ts

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const GRR_REGIONS = ["us", "eu", "in"] as const;
+export type GrrRegion = (typeof GRR_REGIONS)[number];
+
+/** The account's region from BrowserStack auth, or "unknown" when the lookup failed. */
+export type AccountRegion = GrrRegion | "unknown";
+
+interface RegionScope {
+  account: AccountRegion | undefined;
+}
+
+// Per call, not per process: concurrent calls for different accounts each see their own.
+const scope = new AsyncLocalStorage<RegionScope>();
+
+export function withAccountRegion<T>(
+  account: AccountRegion | undefined,
+  fn: () => T,
+): T {
+  return scope.run({ account }, fn);
+}
+
+/** The scope set for the current call, or undefined outside one. */
+export function currentRegionScope(): RegionScope | undefined {
+  return scope.getStore();
+}
+
+/** The account's region, or undefined when it is not known. */
+export function regionOf(
+  account: AccountRegion | undefined,
+): GrrRegion | undefined {
+  return account && account !== "unknown" ? account : undefined;
+}

src/lib/regional-host.ts

@@ -0,0 +1,150 @@
+import appConfig from "../config.js";
+import { SessionType } from "./constants.js";
+import { currentRegionScope, GrrRegion, regionOf } from "./region-context.js";
+
+/** Regions with their own hosts here. Other regions use the default (US) hosts. */
+type RoutedRegion = "us" | "eu";
+
+type Hosts = Record<RoutedRegion, string>;
+
+const AUTOMATE_API: Hosts = {
+  us: "https://api.browserstack.com",
+  eu: "https://api-eu-only.browserstack.com",
+};
+
+const HOSTS = {
+  testManagement: {
+    us: "https://test-management.browserstack.com",
+    eu: "https://test-management-eu.browserstack.com",
+  },
+  automateApi: AUTOMATE_API,
+  appAutomateApi: AUTOMATE_API,
+  appAutomateCloud: {
+    us: "https://api-cloud.browserstack.com",
+    eu: AUTOMATE_API.eu,
+  },
+  appAutomateHub: {
+    us: "hub.browserstack.com",
+    eu: "hub-eu-only.browserstack.com",
+  },
+  automateHubUrl: {
+    us: "https://hub.browserstack.com",
+    eu: "https://hub-eu-only.browserstack.com",
+  },
+  appAutomateHubUrl: {
+    us: "https://hub-cloud.browserstack.com",
+    eu: "https://hub-eu-only.browserstack.com",
+  },
+  accessibilityApi: {
+    us: "https://api-accessibility.browserstack.com",
+    eu: "https://api-accessibility-eu.browserstack.com",
+  },
+  accessibilityDashboard: {
+    us: "https://accessibility.browserstack.com",
+    eu: "https://accessibility-eu.browserstack.com",
+  },
+  appAccessibilityApi: {
+    us: "https://api-app-accessibility.browserstack.com",
+    eu: "https://api-app-accessibility-eu.browserstack.com",
+  },
+  appAccessibilityDashboard: {
+    us: "https://app-accessibility.browserstack.com",
+    eu: "https://app-accessibility-eu.browserstack.com",
+  },
+  observabilityApi: {
+    us: "https://api-observability.browserstack.com",
+    eu: "https://api-observability-eu.browserstack.com",
+  },
+  automationApi: {
+    us: "https://api-automation.browserstack.com",
+    eu: "https://api-automation-eu.browserstack.com",
+  },
+} as const satisfies Record<string, Hosts>;
+
+export type RegionalHostKind = keyof typeof HOSTS;
+
+export function hostFor(kind: RegionalHostKind, region: RoutedRegion): string {
+  return HOSTS[kind][region];
+}
+
+/** True when `hostname` is `kind`'s host in any region, so a link from any region resolves. */
+export function isRegionalHostname(
+  kind: RegionalHostKind,
+  hostname: string,
+): boolean {
+  return Object.values(HOSTS[kind]).some(
+    (host) => new URL(host).hostname === hostname,
+  );
+}
+
+/** This call's account region; undefined outside a call or when the lookup failed. */
+export function currentRegion(): GrrRegion | undefined {
+  return regionOf(currentRegionScope()?.account);
+}
+
+export const REGION_UNKNOWN_MESSAGE =
+  "Could not confirm your BrowserStack account's region. Please retry in a few seconds.";
+
+/** Thrown instead of guessing a host when the account's region could not be looked up. */
+export class AccountRegionUnknownError extends Error {
+  constructor() {
+    super(REGION_UNKNOWN_MESSAGE);
+    this.name = "AccountRegionUnknownError";
+  }
+}
+
+/** Throws when this call's account region could not be looked up. */
+export function assertRegionKnown(): void {
+  if (currentRegionScope()?.account === "unknown") {
+    throw new AccountRegionUnknownError();
+  }
+}
+
+/** The region whose hosts this call uses; throws when the region is unknown. */
+export function routedRegion(): RoutedRegion {
+  assertRegionKnown();
+  return currentRegion() === "eu" ? "eu" : "us";
+}
+
+/** True when this call goes to regional hosts rather than the defaults. */
+export function usesRegionalHosts(): boolean {
+  return currentRegion() === "eu";
+}
+
+/** REST host for a session's product: App Automate or Automate. */
+export function sessionApiHost(sessionType: string): string {
+  return getRegionalHost(
+    sessionType === SessionType.AppAutomate ? "appAutomateApi" : "automateApi",
+  );
+}
+
+/**
+ * An env var's host when it points somewhere other than `kind`'s US default, without a
+ * trailing slash; undefined when it is unset or names the default in any spelling.
+ */
+export function hostOverride(
+  url: string | undefined,
+  kind: RegionalHostKind,
+): string | undefined {
+  const value = url?.trim().replace(/\/+$/, "");
+  if (!value) return undefined;
+  try {
+    if (new URL(value).origin === new URL(HOSTS[kind].us).origin) {
+      return undefined;
+    }
+  } catch {
+    // Not a URL: pass it through as given.
+  }
+  return value;
+}
+
+export function getRegionalHost(kind: RegionalHostKind): string {
+  if (kind === "automationApi") {
+    const override = hostOverride(
+      appConfig.BROWSERSTACK_AUTOMATION_BASE_URL,
+      kind,
+    );
+    if (override) return override;
+  }
+  return hostFor(kind, routedRegion());
+}

src/lib/tm-base-url.ts

@@ -3,7 +3,9 @@ import logger from "../logger.js";
 import { BrowserStackConfig } from "./types.js";
 import { getBrowserStackAuth } from "./get-auth.js";
 import appConfig from "../config.js";
+import { getRegionalHost, usesRegionalHosts } from "./regional-host.js";
 
+// Probe order when the account has no regional hosts here.
 const TM_BASE_URLS = [
   "https://test-management.browserstack.com",
   "https://test-management-eu.browserstack.com",
@@ -15,6 +17,12 @@ let cachedBaseUrl: string | null = null;
 export async function getTMBaseURL(
   config: BrowserStackConfig,
 ): Promise<string> {
+  // A routed region is used as given, like every other product. Any other account keeps
+  // the probe below.
+  if (usesRegionalHosts()) {
+    return getRegionalHost("testManagement");
+  }
+
   // Skip the module-level cache in remote (multi-tenant) mode: it is process-shared,
   // so the first user's region would be served to every subsequent user — breaking
   // requests for users on a different region's BrowserStack account.

src/lib/tool-latency.ts

@@ -1,8 +1,12 @@
 import { RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ClientInfo, withToolCall } from "./instrumentation.js";
 import { withFeedbackHint } from "./feedback-hint.js";
+import { accountRegion } from "./account-region.js";
+import { withAccountRegion } from "./region-context.js";
+import { BrowserStackConfig } from "./types.js";
 
 const WRAPPED = Symbol.for("browserstack.mcp.latencyWrapped");
+const REGION_BOUND = Symbol.for("browserstack.mcp.regionBound");
 
 type AnyHandler = (...args: unknown[]) => unknown;
 
@@ -27,3 +31,25 @@ export function instrumentToolLatency(
     (tool as { handler: unknown }).handler = wrapped;
   }
 }
+
+/** Runs every handler in the account's region, looked up once for `config`. Idempotent. */
+export function bindAccountRegion(
+  tools: Record<string, RegisteredTool>,
+  config: BrowserStackConfig,
+): void {
+  for (const tool of Object.values(tools)) {
+    const inner = tool.handler as unknown;
+    if (typeof inner !== "function") continue;
+    if ((inner as AnyHandler & { [REGION_BOUND]?: true })[REGION_BOUND])
+      continue;
+
+    const bound: AnyHandler & { [REGION_BOUND]?: true } = async (
+      ...args: unknown[]
+    ) => {
+      const account = await accountRegion(config);
+      return withAccountRegion(account, () => (inner as AnyHandler)(...args));
+    };
+    bound[REGION_BOUND] = true;
+    (tool as { handler: unknown }).handler = bound;
+  }
+}