feat: add region configuration support for background worker tasks and queues

Author: gautamsi

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.test.tasks.$taskParam/route.tsx

@@ -59,6 +59,7 @@ import { cn } from "~/utils/cn";
 import { docsPath, v3RunSpanPath, v3TaskParamsSchema, v3TestPath } from "~/utils/pathBuilder";
 import { TestTaskService } from "~/v3/services/testTask.server";
 import { OutOfEntitlementError } from "~/v3/services/triggerTask.server";
+import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { TestTaskData } from "~/v3/testTask";
 import { RunTagInput } from "~/components/runs/v3/RunTagInput";
 import { type loader as queuesLoader } from "~/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.queues";
@@ -237,6 +238,13 @@ export const action: ActionFunction = async ({ request, params }) => {
           );
         }
 
+        if (e instanceof ServiceValidationError) {
+          return redirectBackWithErrorMessage(
+            request,
+            `Unable to start a test run: ${e.message}`
+          );
+        }
+
         logger.error("Failed to start a test run", { error: e instanceof Error ? e.message : e });
 
         return redirectBackWithErrorMessage(

apps/webapp/app/runEngine/concerns/queues.server.ts

@@ -57,6 +57,7 @@ export class DefaultQueueManager implements QueueManager {
   ): Promise<QueueProperties> {
     let queueName: string;
     let lockedQueueId: string | undefined;
+    let resolvedRegion: string | undefined;
 
     // Determine queue name based on lockToVersion and provided options
     if (lockedBackgroundWorker) {
@@ -83,6 +84,17 @@ export class DefaultQueueManager implements QueueManager {
         // Use the validated queue name directly
         queueName = specifiedQueue.name;
         lockedQueueId = specifiedQueue.id;
+
+        // Get task-level region config for the locked worker
+        const lockedTask = await this.prisma.backgroundWorkerTask.findFirst({
+          where: {
+            workerId: lockedBackgroundWorker.id,
+            runtimeEnvironmentId: request.environment.id,
+            slug: request.taskId,
+          },
+          select: { region: true },
+        });
+        resolvedRegion = lockedTask?.region ?? undefined;
       } else {
         // No specific queue name provided, use the default queue for the task on the locked worker
         const lockedTask = await this.prisma.backgroundWorkerTask.findFirst({
@@ -121,6 +133,7 @@ export class DefaultQueueManager implements QueueManager {
         // Use the task's default queue name
         queueName = lockedTask.queue.name;
         lockedQueueId = lockedTask.queue.id;
+        resolvedRegion = lockedTask.region ?? undefined;
       }
     } else {
       // Task is not locked to a specific version, use regular logic
@@ -131,8 +144,10 @@ export class DefaultQueueManager implements QueueManager {
         );
       }
 
-      // Get queue name using the helper for non-locked case (handles provided name or finds default)
-      queueName = await this.getQueueName(request);
+      // Get queue name and task-level region using the helper for non-locked case
+      const queueInfo = await this._getQueueInfo(request);
+      queueName = queueInfo.queueName;
+      resolvedRegion = queueInfo.region ?? undefined;
     }
 
     // Sanitize the final determined queue name once
@@ -148,19 +163,21 @@ export class DefaultQueueManager implements QueueManager {
     return {
       queueName,
       lockedQueueId,
+      resolvedRegion,
     };
   }
 
   async getQueueName(request: TriggerTaskRequest): Promise<string> {
+    const { queueName } = await this._getQueueInfo(request);
+    return queueName;
+  }
+
+  private async _getQueueInfo(
+    request: TriggerTaskRequest
+  ): Promise<{ queueName: string; region?: string | null }> {
     const { taskId, environment, body } = request;
     const { queue } = body.options ?? {};
 
-    // Use extractQueueName to handle double-wrapped queue objects
-    const queueName = extractQueueName(queue);
-    if (queueName) {
-      return queueName;
-    }
-
     const defaultQueueName = `task/${taskId}`;
 
     // Find the current worker for the environment
@@ -172,7 +189,9 @@ export class DefaultQueueManager implements QueueManager {
         environmentId: environment.id,
       });
 
-      return defaultQueueName;
+      // Use extractQueueName to handle double-wrapped queue objects
+      const queueName = extractQueueName(queue);
+      return { queueName: queueName ?? defaultQueueName };
     }
 
     const task = await this.prisma.backgroundWorkerTask.findFirst({
@@ -192,7 +211,14 @@ export class DefaultQueueManager implements QueueManager {
         environmentId: environment.id,
       });
 
-      return defaultQueueName;
+      const queueName = extractQueueName(queue);
+      return { queueName: queueName ?? defaultQueueName };
+    }
+
+    // Use specified queue name if provided, otherwise fall back to task's queue
+    const specifiedQueueName = extractQueueName(queue);
+    if (specifiedQueueName) {
+      return { queueName: specifiedQueueName, region: task.region };
     }
 
     if (!task.queue) {
@@ -202,10 +228,13 @@ export class DefaultQueueManager implements QueueManager {
         queueConfig: task.queueConfig,
       });
 
-      return defaultQueueName;
+      return { queueName: defaultQueueName, region: task.region };
     }
 
-    return task.queue.name ?? defaultQueueName;
+    return {
+      queueName: task.queue.name ?? defaultQueueName,
+      region: task.region,
+    };
   }
 
   async validateQueueLimits(

apps/webapp/app/runEngine/services/triggerTask.server.ts

@@ -268,10 +268,11 @@ export class RunEngineTriggerTaskService {
           })
         : undefined;
 
-      const { queueName, lockedQueueId } = await this.queueConcern.resolveQueueProperties(
-        triggerRequest,
-        lockedToBackgroundWorker ?? undefined
-      );
+      const { queueName, lockedQueueId, resolvedRegion } =
+        await this.queueConcern.resolveQueueProperties(
+          triggerRequest,
+          lockedToBackgroundWorker ?? undefined
+        );
 
       //upsert tags
       const tags = await createTags(
@@ -284,7 +285,10 @@ export class RunEngineTriggerTaskService {
 
       const depth = parentRun ? parentRun.depth + 1 : 0;
 
-      const workerQueue = await this.queueConcern.getWorkerQueue(environment, body.options?.region);
+      // Trigger-time region overrides task-level region, which overrides project default
+      const effectiveRegion = body.options?.region ?? resolvedRegion;
+
+      const workerQueue = await this.queueConcern.getWorkerQueue(environment, effectiveRegion);
 
       try {
         return await this.traceEventConcern.traceRun(

apps/webapp/app/runEngine/types.ts

@@ -48,6 +48,7 @@ export type QueueValidationResult =
 export type QueueProperties = {
   queueName: string;
   lockedQueueId?: string;
+  resolvedRegion?: string;
 };
 
 export type LockedBackgroundWorker = Pick<

apps/webapp/app/v3/services/createBackgroundWorker.server.ts

@@ -277,6 +277,7 @@ async function createWorkerTask(
         retryConfig: task.retry,
         queueConfig: task.queue,
         machineConfig: task.machine,
+        region: task.region,
         triggerSource: task.triggerSource === "schedule" ? "SCHEDULED" : "STANDARD",
         fileId: tasksToBackgroundFiles?.get(task.id) ?? null,
         maxDurationInSeconds: task.maxDuration ? clampMaxDuration(task.maxDuration) : null,

internal-packages/database/prisma/migrations/20260217120000_add_region_config_to_background_worker_task/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "BackgroundWorkerTask" ADD COLUMN "region" TEXT;

internal-packages/database/prisma/schema.prisma

@@ -559,6 +559,7 @@ model BackgroundWorkerTask {
   queueConfig   Json?
   retryConfig   Json?
   machineConfig Json?
+  regionConfig  String?
 
   queueId String?
   queue   TaskQueue? @relation(fields: [queueId], references: [id], onDelete: SetNull, onUpdate: Cascade)

packages/cli-v3/src/entryPoints/dev-index-worker.ts

@@ -147,6 +147,20 @@ if (typeof config.machine === "string") {
   });
 }
 
+// If the config has a region, we need to apply it to all tasks that don't have a region
+if (typeof config.region === "string") {
+  tasks = tasks.map((task) => {
+    if (typeof task.region !== "string") {
+      return {
+        ...task,
+        region: config.region,
+      } satisfies TaskManifest;
+    }
+
+    return task;
+  });
+}
+
 await sendMessageInCatalog(
   indexerToWorkerMessages,
   "INDEX_COMPLETE",

packages/cli-v3/src/entryPoints/managed-index-worker.ts

@@ -147,6 +147,20 @@ if (typeof config.machine === "string") {
   });
 }
 
+// If the config has a region, we need to apply it to all tasks that don't have a region
+if (typeof config.region === "string") {
+  tasks = tasks.map((task) => {
+    if (typeof task.region !== "string") {
+      return {
+        ...task,
+        region: config.region,
+      } satisfies TaskManifest;
+    }
+
+    return task;
+  });
+}
+
 const processKeepAlive = config.processKeepAlive ?? config.experimental_processKeepAlive;
 
 await sendMessageInCatalog(

packages/core/src/v3/config.ts

@@ -141,6 +141,13 @@ export type TriggerConfig = {
    */
   machine?: MachinePresetName;
 
+  /**
+   * The default region to run your tasks in. You can override this on a per-task basis or at trigger time.
+   *
+   * Check the Regions page in the dashboard for regions that are available to you.
+   */
+  region?: string;
+
   /**
    * Set the log level for the logger. Defaults to "info", so you will see "log", "info", "warn", and "error" messages, but not "debug" messages.
    *