Implement OpenTelemetry shutdown handling and enhance database connection management

- Added `shutdownOTel` function to gracefully shut down OpenTelemetry SDK during process termination.
- Updated `prisma-client.tsx` to call `shutdownOTel` on SIGTERM, ensuring proper cleanup of background tasks and database connections.
- Improved pool max configuration logic for PostgreSQL client to handle invalid values more robustly.
- Enhanced trusted proxy handling in `end-users.tsx` to include "cloudrun" as a valid option.

These changes improve observability and resource management in the backend, particularly for Cloud Run deployments.

Author: mantrakp04

apps/backend/src/instrumentation.ts

@@ -32,6 +32,12 @@ function getDevTraceExporter() {
   return undefined;
 }
 
+let otelSdk: { shutdown(): Promise<void> } | undefined;
+
+export async function shutdownOTel() {
+  await otelSdk?.shutdown();
+}
+
 async function registerOTelProvider() {
   const instrumentations = getOTelInstrumentations();
   const devExporter = getDevTraceExporter();
@@ -44,8 +50,8 @@ async function registerOTelProvider() {
       instrumentations,
       ...devExporter ? { traceExporter: devExporter } : {},
     });
-  } else {
-    // On Cloud Run / self-hosted: use standard @opentelemetry/sdk-node
+  } else if (getNextRuntime() === "nodejs") {
+    // On Cloud Run / self-hosted: use standard @opentelemetry/sdk-node (Node.js only)
     const { NodeSDK } = await import("@opentelemetry/sdk-node");
     const otelEndpoint = getEnvVariable("OTEL_EXPORTER_OTLP_ENDPOINT", "");
     const exporter = devExporter ?? (otelEndpoint ? new OTLPTraceExporter({ url: otelEndpoint }) : undefined);
@@ -57,6 +63,7 @@ async function registerOTelProvider() {
       ...(exporter ? { traceExporter: exporter as any } : {}),
     });
     sdk.start();
+    otelSdk = sdk;
   }
 }
 

apps/backend/src/lib/end-users.tsx

@@ -174,7 +174,7 @@ export async function getEndUserInfo(): Promise<
   if (isClaimingToBeBrowser) {
     // Determine which proxy we trust based on deployment configuration.
     // These headers can only be trusted when the origin is exclusively reachable through the proxy;
-    // STACK_TRUSTED_PROXY should be set to "vercel", "cloudflare", or left empty/unset for no proxy trust.
+    // STACK_TRUSTED_PROXY should be set to "vercel", "cloudflare", "cloudrun", or left empty/unset for no proxy trust.
     const trustedProxy = getEnvVariable("STACK_TRUSTED_PROXY", "").toLowerCase().trim();
     if (trustedProxy !== "" && trustedProxy !== "vercel" && trustedProxy !== "cloudflare" && trustedProxy !== "cloudrun") {
       throw new StackAssertionError(`STACK_TRUSTED_PROXY must be "vercel", "cloudflare", "cloudrun", or empty/unset, but got: "${trustedProxy}"`);
@@ -227,6 +227,51 @@ import.meta.vitest?.describe("getBrowserEndUserInfo(...)", () => {
     });
   });
 
+  test("trusts first x-forwarded-for entry when Cloud Run proxy is configured", () => {
+    const result = getBrowserEndUserInfo(new Headers({
+      "user-agent": "Mozilla/5.0",
+      "x-forwarded-for": "198.51.100.42, 10.0.0.1",
+    }), "cloudrun");
+
+    expect(result).toEqual({
+      maybeSpoofed: false,
+      exactInfo: {
+        ip: "198.51.100.42",
+      },
+    });
+  });
+
+  test("does not expose x-forwarded-for as spoofable when Cloud Run proxy is configured", () => {
+    const result = getBrowserEndUserInfo(new Headers({
+      "user-agent": "Mozilla/5.0",
+      "x-forwarded-for": "198.51.100.42",
+      "x-real-ip": "10.0.0.1",
+    }), "cloudrun");
+
+    expect(result).toEqual({
+      maybeSpoofed: false,
+      exactInfo: {
+        ip: "198.51.100.42",
+      },
+    });
+  });
+
+  test("does not trust geo headers for Cloud Run proxy", () => {
+    const result = getBrowserEndUserInfo(new Headers({
+      "user-agent": "Mozilla/5.0",
+      "x-forwarded-for": "198.51.100.42",
+      "x-vercel-ip-country": "US",
+      "cf-ipcountry": "DE",
+    }), "cloudrun");
+
+    expect(result).toEqual({
+      maybeSpoofed: false,
+      exactInfo: {
+        ip: "198.51.100.42",
+      },
+    });
+  });
+
   test("keeps trusted proxy geo headers when the trusted IP header is present", () => {
     const result = getBrowserEndUserInfo(new Headers({
       "user-agent": "Mozilla/5.0",

apps/backend/src/prisma-client.tsx

@@ -10,6 +10,8 @@ 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";
@@ -84,7 +86,8 @@ function getPostgresPrismaClient(connectionString: string, poolLabel?: string) {
   let postgresPrismaClient = postgresPrismaClientsStore.get(connectionString);
   if (!postgresPrismaClient) {
     const schema = getSchemaFromConnectionString(connectionString);
-    const poolMax = parseInt(getEnvVariable("STACK_DATABASE_POOL_MAX", "25"));
+    const poolMaxRaw = parseInt(getEnvVariable("STACK_DATABASE_POOL_MAX", "25"), 10);
+    const poolMax = Number.isFinite(poolMaxRaw) && poolMaxRaw > 0 ? poolMaxRaw : 25;
     const pool = new Pool({ connectionString, max: poolMax });
     pool.on('error', (err) => {
       // Prevent unhandled rejections from crashing the process (e.g. on Cloud Run)
@@ -102,24 +105,20 @@ function getPostgresPrismaClient(connectionString: string, poolLabel?: string) {
 }
 
 // Graceful shutdown for non-Vercel runtimes (Cloud Run sends SIGTERM before shutdown)
-if (!getEnvVariable("VERCEL", "")) {
+if (!getEnvVariable("VERCEL", "") && !globalVar.__stack_prisma_sigterm_registered) {
+  globalVar.__stack_prisma_sigterm_registered = true;
   process.on("SIGTERM", () => {
     runAsynchronously(async () => {
       console.log("[SIGTERM] Draining background tasks and database connections...");
-      try {
-        const { drainInFlightPromises } = await import("./utils/vercel");
-        await drainInFlightPromises(8000);
-      } catch {
-        // vercel utils may not be available in all contexts
-      }
+      await drainInFlightPromises(8000);
+      await shutdownOTel();
       for (const [, entry] of postgresPrismaClientsStore) {
-        await entry.client.$disconnect().catch(() => {});
+        await entry.client.$disconnect();
       }
       for (const [, client] of prismaClientsStore.neon) {
-        await client.$disconnect().catch(() => {});
+        await client.$disconnect();
       }
-      console.log("[SIGTERM] Shutdown complete.");
-      process.exit(0);
+      console.log("[SIGTERM] Completed draining background tasks and database connections.");
     });
   });
 }

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

@@ -61,12 +61,17 @@ async function fetchGcpIdToken(audience: string): Promise<string> {
   return await response.text();
 }
 
+let kmsClientCache: KMSClient | undefined;
+
 async function getKmsClient() {
-  return new KMSClient({
-    region: getEnvVariable("STACK_AWS_REGION"),
-    endpoint: getEnvVariable("STACK_AWS_KMS_ENDPOINT"),
-    credentials: await getAwsCredentials(),
-  });
+  if (!kmsClientCache) {
+    kmsClientCache = new KMSClient({
+      region: getEnvVariable("STACK_AWS_REGION"),
+      endpoint: getEnvVariable("STACK_AWS_KMS_ENDPOINT"),
+      credentials: await getAwsCredentials(),
+    });
+  }
+  return kmsClientCache;
 }
 
 async function getOrCreateKekId(): Promise<string> {