Refactor fallback URL handling and enhance backend API resilience

- Removed hardcoded fallback API URL configurations from environment files and the GitHub Actions workflow.
- Introduced a new method for dynamically resolving fallback URLs based on the primary API URL.
- Updated the StackClientInterface to support an ordered list of API URLs for improved request routing and sticky fallback behavior.
- Added tests for the new fallback URL parsing and validation logic to ensure robustness.

These changes streamline the fallback mechanism and improve the SDK's ability to handle backend failures effectively.

Author: mantrakp04

.github/workflows/e2e-fallback-tests.yaml

@@ -65,14 +65,6 @@ jobs:
           cp examples/supabase/.env.development examples/supabase/.env.test.local
           cp examples/convex/.env.development examples/convex/.env.test.local
 
-      - name: Configure fallback backend URL
-        run: |
-          echo "NEXT_PUBLIC_STACK_FALLBACK_API_URL=http://localhost:8110" >> apps/backend/.env.test.local
-          echo "NEXT_PUBLIC_STACK_FALLBACK_API_URL=http://localhost:8110" >> apps/dashboard/.env.test.local
-          echo "NEXT_PUBLIC_STACK_FALLBACK_API_URL=http://localhost:8110" >> apps/e2e/.env.test.local
-          echo "NEXT_PUBLIC_STACK_FALLBACK_API_URL=http://localhost:8110" >> examples/demo/.env.test.local
-          echo "STACK_BACKEND_BASE_URL=http://localhost:8110" >> apps/e2e/.env.test.local
-
       - name: Build
         run: pnpm build
 

apps/backend/.env.development

@@ -1,5 +1,4 @@
 NEXT_PUBLIC_STACK_API_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02
-NEXT_PUBLIC_STACK_FALLBACK_API_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}10
 NEXT_PUBLIC_STACK_DASHBOARD_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}01
 NEXT_PUBLIC_STACK_HOSTED_HANDLER_DOMAIN_SUFFIX=.localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}09
 NEXT_PUBLIC_STACK_IS_LOCAL_EMULATOR=false

apps/backend/src/app/api/latest/internal/backend-urls/route.test.tsx

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { parseAndValidateConfig } from './route';
+
+describe('parseAndValidateConfig', () => {
+  it('should parse a single entry with probability 1', () => {
+    const result = parseAndValidateConfig({
+      "1": ["https://api.stack-auth.com"],
+    });
+    expect(result).toEqual([
+      { probability: 1, urls: ["https://api.stack-auth.com"] },
+    ]);
+  });
+
+  it('should parse multiple entries', () => {
+    const result = parseAndValidateConfig({
+      "0.7": ["https://api.stack-auth.com", "https://api2.stack-auth.com"],
+      "0.3": ["https://api2.stack-auth.com", "https://api.stack-auth.com"],
+    });
+    expect(result).toEqual([
+      { probability: 0.7, urls: ["https://api.stack-auth.com", "https://api2.stack-auth.com"] },
+      { probability: 0.3, urls: ["https://api2.stack-auth.com", "https://api.stack-auth.com"] },
+    ]);
+  });
+
+  it('should allow probabilities summing to less than 1', () => {
+    const result = parseAndValidateConfig({
+      "0.5": ["https://api.stack-auth.com"],
+      "0.3": ["https://api2.stack-auth.com"],
+    });
+    expect(result).toHaveLength(2);
+  });
+
+  it('should reject non-object input', () => {
+    expect(() => parseAndValidateConfig("string")).toThrow("must be a JSON object");
+    expect(() => parseAndValidateConfig(null)).toThrow("must be a JSON object");
+    expect(() => parseAndValidateConfig([])).toThrow("must be a JSON object");
+    expect(() => parseAndValidateConfig(42)).toThrow("must be a JSON object");
+  });
+
+  it('should reject empty object', () => {
+    expect(() => parseAndValidateConfig({})).toThrow("at least one entry");
+  });
+
+  it('should reject invalid probability keys', () => {
+    expect(() => parseAndValidateConfig({ "abc": ["https://a.com"] })).toThrow("must be a number between 0 and 1");
+    expect(() => parseAndValidateConfig({ "-0.1": ["https://a.com"] })).toThrow("must be a number between 0 and 1");
+    expect(() => parseAndValidateConfig({ "1.5": ["https://a.com"] })).toThrow("must be a number between 0 and 1");
+  });
+
+  it('should reject probabilities summing to more than 1', () => {
+    expect(() => parseAndValidateConfig({
+      "0.6": ["https://api.stack-auth.com"],
+      "0.5": ["https://api2.stack-auth.com"],
+    })).toThrow("exceeds 1");
+  });
+
+  it('should reject invalid URL values', () => {
+    expect(() => parseAndValidateConfig({ "1": ["not-a-url"] })).toThrow();
+  });
+
+  it('should reject empty URL arrays', () => {
+    expect(() => parseAndValidateConfig({ "1": [] })).toThrow();
+  });
+
+  it('should reject non-array values', () => {
+    expect(() => parseAndValidateConfig({ "1": "https://api.stack-auth.com" })).toThrow();
+  });
+});

apps/backend/src/app/api/latest/internal/backend-urls/route.tsx

@@ -0,0 +1,96 @@
+import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { urlSchema, yupArray, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
+import { StackAssertionError } from "@stackframe/stack-shared/dist/utils/errors";
+import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
+import { getDefaultApiUrls } from "@stackframe/stack-shared/dist/utils/urls";
+
+/**
+ * Env var format: JSON object mapping probability (as string number) to URL arrays.
+ * Probabilities must sum to <= 1. Remaining probability uses the last entry as fallback.
+ *
+ * Example:
+ * {
+ *   "0.7": ["https://api.stack-auth.com", "https://api2.stack-auth.com"],
+ *   "0.3": ["https://api2.stack-auth.com", "https://api.stack-auth.com"]
+ * }
+ */
+
+const urlsArraySchema = yupArray(urlSchema.defined()).min(1).defined();
+
+export function parseAndValidateConfig(raw: unknown): Array<{ probability: number, urls: string[] }> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new StackAssertionError("STACK_BACKEND_URLS_CONFIG must be a JSON object mapping probability strings to URL arrays");
+  }
+
+  const entries = Object.entries(raw as Record<string, unknown>).map(([key, value]) => {
+    const probability = Number(key);
+    if (isNaN(probability) || probability < 0 || probability > 1) {
+      throw new StackAssertionError(`Invalid probability key "${key}": must be a number between 0 and 1`);
+    }
+    const urls = urlsArraySchema.validateSync(value);
+    return { probability, urls };
+  });
+
+  if (entries.length === 0) {
+    throw new StackAssertionError("STACK_BACKEND_URLS_CONFIG must have at least one entry");
+  }
+
+  const sum = entries.reduce((acc, e) => acc + e.probability, 0);
+  if (sum > 1 + 1e-9) {
+    throw new StackAssertionError(`Probabilities sum to ${sum}, which exceeds 1`);
+  }
+
+  return entries;
+}
+
+let cachedEntries: ReturnType<typeof parseAndValidateConfig> | undefined;
+function getCachedConfig() {
+  if (!cachedEntries) {
+    const rawEnv = getEnvVariable("STACK_BACKEND_URLS_CONFIG", "");
+    cachedEntries = rawEnv
+      ? parseAndValidateConfig(JSON.parse(rawEnv))
+      : [{ probability: 1, urls: getDefaultApiUrls(getEnvVariable("NEXT_PUBLIC_STACK_API_URL")) }];
+  }
+  return cachedEntries;
+}
+
+export const GET = createSmartRouteHandler({
+  metadata: {
+    hidden: true,
+    summary: "Get backend URLs",
+    description: "Returns a prioritized list of backend API URLs for client-side failover",
+    tags: ["Internal"],
+  },
+  request: yupObject({
+    method: yupString().oneOf(["GET"]).defined(),
+  }),
+  response: yupObject({
+    statusCode: yupNumber().oneOf([200]).defined(),
+    bodyType: yupString().oneOf(["json"]).defined(),
+    body: yupObject({
+      urls: yupArray(yupString().defined()).defined(),
+    }).defined(),
+  }),
+  handler: async () => {
+    const entries = getCachedConfig();
+
+    const roll = Math.random();
+    let cumulative = 0;
+    for (const entry of entries) {
+      cumulative += entry.probability;
+      if (roll < cumulative) {
+        return {
+          statusCode: 200,
+          bodyType: "json",
+          body: { urls: entry.urls },
+        } as const;
+      }
+    }
+
+    return {
+      statusCode: 200,
+      bodyType: "json",
+      body: { urls: entries[entries.length - 1].urls },
+    } as const;
+  },
+});

apps/backend/src/prisma-client.tsx

@@ -10,8 +10,6 @@ import { captureError, StackAssertionError } from "@stackframe/stack-shared/dist
 import { globalVar } from "@stackframe/stack-shared/dist/utils/globals";
 import { deepPlainEquals, filterUndefined, typedFromEntries, typedKeys } from "@stackframe/stack-shared/dist/utils/objects";
 import { concatStacktracesIfRejected, ignoreUnhandledRejection, runAsynchronously, wait } from "@stackframe/stack-shared/dist/utils/promises";
-import { drainInFlightPromises } from "./utils/background-tasks";
-import { shutdownOTel } from "./instrumentation";
 import { throwingProxy } from "@stackframe/stack-shared/dist/utils/proxies";
 import { Result } from "@stackframe/stack-shared/dist/utils/results";
 import { traceSpan } from "@stackframe/stack-shared/dist/utils/telemetry";
@@ -20,9 +18,11 @@ import net from "node:net";
 import { Pool } from "pg";
 import { isPromise } from "util/types";
 import { runMigrationNeeded } from "./auto-migrations";
+import { shutdownOTel } from "./instrumentation";
 import { registerPgPool } from "./lib/dev-perf-stats";
 import { Tenancy } from "./lib/tenancies";
 import { ensurePolyfilled } from "./polyfills";
+import { drainInFlightPromises } from "./utils/background-tasks";
 
 // just ensure we're polyfilled because this file relies on envvars being expanded
 ensurePolyfilled();
@@ -108,17 +108,25 @@ function getPostgresPrismaClient(connectionString: string, poolLabel?: string) {
 if (!getEnvVariable("VERCEL", "") && !globalVar.__stack_prisma_sigterm_registered) {
   globalVar.__stack_prisma_sigterm_registered = true;
   process.on("SIGTERM", () => {
+    // Keep the event loop alive so Node doesn't exit before the drain completes.
+    // 10s timeout > 8s drain timeout to ensure we have enough time.
+    const keepAlive = setTimeout(() => {}, 10_000);
+
     runAsynchronously(async () => {
-      console.log("[SIGTERM] Draining background tasks and database connections...");
-      await drainInFlightPromises(8000);
-      await shutdownOTel();
-      for (const [, entry] of postgresPrismaClientsStore) {
-        await entry.client.$disconnect();
-      }
-      for (const [, client] of prismaClientsStore.neon) {
-        await client.$disconnect();
+      try {
+        console.log("[SIGTERM] Draining background tasks and database connections...");
+        await drainInFlightPromises(8000);
+        await shutdownOTel();
+        for (const [, entry] of postgresPrismaClientsStore) {
+          await entry.client.$disconnect();
+        }
+        for (const [, client] of prismaClientsStore.neon) {
+          await client.$disconnect();
+        }
+        console.log("[SIGTERM] Completed draining background tasks and database connections.");
+      } finally {
+        clearTimeout(keepAlive);
       }
-      console.log("[SIGTERM] Completed draining background tasks and database connections.");
     });
   });
 }

apps/dashboard/.env.development

@@ -1,5 +1,4 @@
 NEXT_PUBLIC_STACK_API_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02
-NEXT_PUBLIC_STACK_FALLBACK_API_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}10
 NEXT_PUBLIC_STACK_DOCS_BASE_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}04
 NEXT_PUBLIC_STACK_HOSTED_HANDLER_DOMAIN_SUFFIX=.localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}09
 NEXT_PUBLIC_STACK_IS_LOCAL_EMULATOR=false

docker/backend/Dockerfile

@@ -1,5 +1,4 @@
-# Backend for Cloud Run / self-hosted deployment.
-# Includes migration script for database setup.
+# Backend for Cloud Run / self-hosted deployment (fallback backend server).
 # Connects to the same AWS services (RDS, S3, KMS) as the Vercel deployment.
 #
 # Build:  docker build -f docker/backend/Dockerfile -t stack-backend .
@@ -57,9 +56,6 @@ ENV NEXT_CONFIG_OUTPUT=standalone
 # Build backend only
 RUN pnpm turbo run docker-build --filter=@stackframe/backend...
 
-# Build the migration script
-RUN cd apps/backend && pnpm build-self-host-migration-script
-
 
 # Final image
 FROM node:${NODE_VERSION}-slim
@@ -71,16 +67,13 @@ RUN apt-get update && \
     apt-get install -y --no-install-recommends openssl && \
     rm -rf /var/lib/apt/lists/*
 
-# Copy built backend (standalone)
+# Copy Next.js standalone output — this includes a traced, minimal copy of
+# node_modules/ and packages/ (only the files the server actually imports).
 COPY --from=builder --chown=node:node /app/apps/backend/.next/standalone ./
 COPY --from=builder --chown=node:node /app/apps/backend/.next/static ./apps/backend/.next/static
-COPY --from=builder --chown=node:node /app/apps/backend/prisma ./apps/backend/prisma
-COPY --from=builder --chown=node:node /app/apps/backend/dist ./apps/backend/dist
-COPY --from=builder --chown=node:node /app/apps/backend/node_modules ./apps/backend/node_modules
 
-# Restore workspace node_modules and packages needed by runtime scripts (e.g. migration script)
-COPY --from=builder --chown=node:node /app/node_modules ./node_modules
-COPY --from=builder --chown=node:node /app/packages ./packages
+# Prisma schema (needed at runtime by Prisma client)
+COPY --from=builder --chown=node:node /app/apps/backend/prisma ./apps/backend/prisma
 
 ENV NODE_ENV=production
 ENV PORT=8102

examples/demo/.env.development

@@ -1,7 +1,6 @@
 # Contains the credentials for the internal project of Stack's default development environment setup.
 # Do not use in a production environment, instead replace it with actual values gathered from https://app.stack-auth.com.
 NEXT_PUBLIC_STACK_API_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02
-NEXT_PUBLIC_STACK_FALLBACK_API_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}10
 NEXT_PUBLIC_STACK_PROJECT_ID=internal
 NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=this-publishable-client-key-is-for-local-development-only
 STACK_SECRET_SERVER_KEY=this-secret-server-key-is-for-local-development-only

examples/demo/src/app/fallback-test/client.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useStackApp, useUser } from "@stackframe/stack";
+import { runAsynchronously } from "@stackframe/stack-shared/dist/utils/promises";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -62,7 +63,7 @@ export function FallbackTestClient() {
   }, [app, user, addLog]);
 
   useEffect(() => {
-    void runTests();
+    runAsynchronously(runTests());
   }, []);  // eslint-disable-line react-hooks/exhaustive-deps
 
   return (

packages/stack-shared/src/helpers/vault/server-side.ts

@@ -31,11 +31,15 @@ async function getAwsCredentials() {
   if (gcpWifRoleArn) {
     const { fromWebToken } = await import("@aws-sdk/credential-provider-web-identity");
     const audience = getEnvVariable("STACK_AWS_GCP_WIF_AUDIENCE", "sts.amazonaws.com");
-    return fromWebToken({
-      roleArn: gcpWifRoleArn,
-      roleSessionName: "stack-backend-cloudrun",
-      webIdentityToken: await fetchGcpIdToken(audience),
-    });
+    // Return a provider that fetches a fresh GCP ID token on each invocation.
+    // GCP metadata tokens expire after ~1h, so we can't bake a single token into the closure.
+    return async () => {
+      return await fromWebToken({
+        roleArn: gcpWifRoleArn,
+        roleSessionName: "stack-backend-cloudrun",
+        webIdentityToken: await fetchGcpIdToken(audience),
+      })();
+    };
   }
 
   // 3. Static credentials: fallback for self-hosted / local development