feat(sdk,core,webapp): let tasks declare the region(s) they may run in

Adds a task-level `region` option, a single region or a list, so a task
definition can restrict where its runs execute instead of relying on every
trigger call site passing `{ region }` or on the project default.

Placement at trigger time:
- a `region` passed when triggering must be in the task's list, otherwise
  the trigger is rejected with a 400 naming the allowed regions
- with no trigger-time region, the project's default region is used when
  the task allows it, otherwise the first region in the list
- tasks without `region` keep today's behaviour; DEV ignores it, matching
  the existing per-trigger option
- the existing access checks (hidden groups, project allowlists, MICROVM
  access, other projects' UNMANAGED groups) still apply to the picked region

Deploys now fail early with a message naming the task and region when a
listed region doesn't exist or isn't available to the project.

The SDK normalises `region` into a `regions` list in the task manifest,
which is persisted as a text-array column on BackgroundWorkerTask and rides
on the cached task-metadata entry, so the trigger hot path enforces it with
no additional query. Pre-existing cache entries decode as unconstrained.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: jingerpie

.changeset/task-level-region.md

@@ -0,0 +1,17 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Tasks can now declare the region(s) they may run in with `region: "eu-central-1"` or `region: ["eu-central-1", "us-east-1"]` in the task definition. A `region` passed when triggering must be one of them, otherwise the trigger is rejected. When no region is passed, the project's default region is used if the task allows it, otherwise the first region in the list. Deploys fail early if a task names a region that doesn't exist or isn't available to the project. The option is ignored in dev.
+
+```ts
+export const euOnlyTask = task({
+  id: "eu-only-task",
+  region: "eu-central-1",
+  run: async (payload) => {
+    // ...
+  },
+});
+```

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

@@ -9,8 +9,12 @@ import type {
   QueueProperties,
   QueueValidationResult,
   TriggerTaskRequest,
+  WorkerQueueOptions,
 } from "../types";
-import { WorkerGroupService } from "~/v3/services/worker/workerGroupService.server";
+import {
+  RegionNotAllowedForTaskError,
+  WorkerGroupService,
+} from "~/v3/services/worker/workerGroupService.server";
 import type { RunEngine } from "~/v3/runEngine.server";
 import { env } from "~/env.server";
 import { tryCatch } from "@trigger.dev/core/v3";
@@ -95,6 +99,7 @@ export class DefaultQueueManager implements QueueManager {
     let lockedQueueId: string | undefined;
     let taskTtl: string | null | undefined;
     let taskKind: string | undefined;
+    let taskRegions: string[] | undefined;
 
     // Determine queue name based on lockToVersion and provided options
     if (lockedBackgroundWorker) {
@@ -146,6 +151,7 @@ export class DefaultQueueManager implements QueueManager {
           taskTtl = lockedMeta?.ttl ?? undefined;
         }
         taskKind = lockedMeta?.triggerSource;
+        taskRegions = lockedMeta?.regions;
       } else {
         // No queue override - resolve default queue + TTL + triggerSource via cache,
         // falling back to a single BackgroundWorkerTask lookup on miss.
@@ -184,6 +190,7 @@ export class DefaultQueueManager implements QueueManager {
         queueName = lockedMeta.queueName;
         lockedQueueId = lockedMeta.queueId ?? undefined;
         taskKind = lockedMeta.triggerSource;
+        taskRegions = lockedMeta.regions;
       }
     } else {
       // Task is not locked to a specific version, use regular logic
@@ -199,6 +206,7 @@ export class DefaultQueueManager implements QueueManager {
       queueName = taskInfo.queueName;
       taskTtl = taskInfo.taskTtl;
       taskKind = taskInfo.taskKind;
+      taskRegions = taskInfo.taskRegions;
     }
 
     // Sanitize the final determined queue name once
@@ -216,12 +224,16 @@ export class DefaultQueueManager implements QueueManager {
       lockedQueueId,
       taskTtl,
       taskKind,
+      taskRegions,
     };
   }
 
-  private async getTaskQueueInfo(
-    request: TriggerTaskRequest
-  ): Promise<{ queueName: string; taskTtl?: string | null; taskKind?: string | undefined }> {
+  private async getTaskQueueInfo(request: TriggerTaskRequest): Promise<{
+    queueName: string;
+    taskTtl?: string | null;
+    taskKind?: string | undefined;
+    taskRegions?: string[];
+  }> {
     const { taskId, environment, body } = request;
     const { queue } = body.options ?? {};
 
@@ -243,6 +255,7 @@ export class DefaultQueueManager implements QueueManager {
         queueName: overriddenQueueName,
         taskTtl: meta?.ttl ?? undefined,
         taskKind: meta?.triggerSource,
+        taskRegions: meta?.regions,
       };
     }
 
@@ -259,10 +272,20 @@ export class DefaultQueueManager implements QueueManager {
         taskId,
         environmentId: environment.id,
       });
-      return { queueName: defaultQueueName, taskTtl: meta.ttl, taskKind: meta.triggerSource };
+      return {
+        queueName: defaultQueueName,
+        taskTtl: meta.ttl,
+        taskKind: meta.triggerSource,
+        taskRegions: meta.regions,
+      };
     }
 
-    return { queueName: meta.queueName, taskTtl: meta.ttl, taskKind: meta.triggerSource };
+    return {
+      queueName: meta.queueName,
+      taskTtl: meta.ttl,
+      taskKind: meta.triggerSource,
+      taskRegions: meta.regions,
+    };
   }
 
   /**
@@ -320,6 +343,7 @@ export class DefaultQueueManager implements QueueManager {
       triggerSource: row.triggerSource,
       queueId: row.queue?.id ?? null,
       queueName: row.queue?.name ?? "",
+      regions: row.regions,
     };
 
     // Fire-and-forget back-fill — `setByWorker` upserts the single field and
@@ -340,6 +364,7 @@ export class DefaultQueueManager implements QueueManager {
       select: {
         ttl: true,
         triggerSource: true,
+        regions: true,
         queue: { select: { id: true, name: true } },
       },
     });
@@ -378,6 +403,7 @@ export class DefaultQueueManager implements QueueManager {
       select: {
         ttl: true,
         triggerSource: true,
+        regions: true,
         queue: { select: { id: true, name: true } },
       },
     });
@@ -395,6 +421,7 @@ export class DefaultQueueManager implements QueueManager {
       triggerSource: row.triggerSource,
       queueId: row.queue?.id ?? null,
       queueName: row.queue?.name ?? "",
+      regions: row.regions,
     };
 
     // Fire-and-forget back-fill — atomically upserts the slug into both
@@ -438,8 +465,10 @@ export class DefaultQueueManager implements QueueManager {
 
   async getWorkerQueue(
     environment: AuthenticatedEnvironment,
-    regionOverride?: string
+    options?: WorkerQueueOptions
   ): Promise<{ masterQueue: string; enableFastPath: boolean } | undefined> {
+    // Dev runs always dequeue from the environment's own queue, so both the
+    // per-trigger region and the task-level region list are ignored here.
     if (environment.type === "DEVELOPMENT") {
       return { masterQueue: environment.id, enableFastPath: true };
     }
@@ -452,11 +481,19 @@ export class DefaultQueueManager implements QueueManager {
     const [error, workerGroup] = await tryCatch(
       workerGroupService.getDefaultWorkerGroupForProject({
         projectId: environment.projectId,
-        regionOverride,
+        regionOverride: options?.regionOverride,
+        allowedRegions: options?.taskRegions,
+        taskId: options?.taskId,
       })
     );
 
     if (error) {
+      // A per-trigger region outside the task definition's list is a caller
+      // mistake, so surface it as a 400 rather than the generic 422 below.
+      if (error instanceof RegionNotAllowedForTaskError) {
+        throw new ServiceValidationError(error.message, 400);
+      }
+
       // getDefaultWorkerGroupForProject queries the writer DB. A Prisma
       // infrastructure error (e.g. P1001 "Can't reach database server", whose
       // message carries the DB hostname) must NOT be promoted into a

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

@@ -445,7 +445,7 @@ export class RunEngineTriggerTaskService {
           const parkedOnExternalDeploymentId =
             externalDeploymentResolution?.outcome === "park" ? externalDeploymentId : undefined;
 
-          const { queueName, lockedQueueId, taskTtl, taskKind } =
+          const { queueName, lockedQueueId, taskTtl, taskKind, taskRegions } =
             await this.queueConcern.resolveQueueProperties(
               triggerRequest,
               lockedToBackgroundWorker ?? undefined
@@ -497,10 +497,13 @@ export class RunEngineTriggerTaskService {
 
           const depth = parentRun ? parentRun.depth + 1 : 0;
 
-          const workerQueueResult = await this.queueConcern.getWorkerQueue(
-            environment,
-            body.options?.region
-          );
+          // The task definition's region list (if any) rode in on the cached task
+          // metadata above, so no extra query is needed to enforce it here.
+          const workerQueueResult = await this.queueConcern.getWorkerQueue(environment, {
+            regionOverride: body.options?.region,
+            taskRegions,
+            taskId,
+          });
           const baseWorkerQueue = workerQueueResult?.masterQueue;
           const enableFastPath = workerQueueResult?.enableFastPath ?? false;
 

apps/webapp/app/runEngine/types.ts

@@ -46,6 +46,17 @@ export type QueueProperties = {
   lockedQueueId?: string;
   taskTtl?: string | null;
   taskKind?: string;
+  /** Regions the task definition allows (worker group master queues). Empty/undefined = unconstrained. */
+  taskRegions?: string[];
+};
+
+export type WorkerQueueOptions = {
+  /** Per-trigger `region` option. */
+  regionOverride?: string;
+  /** Regions the task definition allows; the resolved region must be one of them. */
+  taskRegions?: string[];
+  /** Task identifier, used only for error messages. */
+  taskId?: string;
 };
 
 export type LockedBackgroundWorker = Pick<
@@ -66,7 +77,7 @@ export interface QueueManager {
   ): Promise<QueueValidationResult>;
   getWorkerQueue(
     env: AuthenticatedEnvironment,
-    regionOverride?: string
+    options?: WorkerQueueOptions
   ): Promise<{ masterQueue: string; enableFastPath: boolean } | undefined>;
 }
 

apps/webapp/app/services/taskMetadataCache.server.ts

@@ -8,6 +8,8 @@ export type TaskMetadataEntry = {
   triggerSource: TaskTriggerSource;
   queueId: string | null;
   queueName: string;
+  /** Regions the task may run in (worker group master queues). Empty = no constraint. */
+  regions: string[];
 };
 
 export interface TaskMetadataCache {
@@ -57,6 +59,8 @@ type EncodedEntry = {
   k: TaskTriggerSource;
   q: string | null;
   n: string;
+  /** Regions; omitted when empty so no-region entries stay byte-identical to pre-regions entries. */
+  r?: string[];
 };
 
 function encode(entry: TaskMetadataEntry): string {
@@ -65,6 +69,7 @@ function encode(entry: TaskMetadataEntry): string {
     k: entry.triggerSource,
     q: entry.queueId,
     n: entry.queueName,
+    r: entry.regions.length > 0 ? entry.regions : undefined,
   };
   return JSON.stringify(payload);
 }
@@ -78,6 +83,8 @@ function decode(slug: string, raw: string): TaskMetadataEntry | null {
       triggerSource: parsed.k,
       queueId: parsed.q,
       queueName: parsed.n,
+      // Entries written before regions existed have no `r`; treat as unconstrained.
+      regions: Array.isArray(parsed.r) ? parsed.r : [],
     };
   } catch (error) {
     logger.error("Failed to decode task metadata cache entry", { slug, error });

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

@@ -119,6 +119,7 @@ export class ChangeCurrentDeploymentService extends BaseService {
           slug: true,
           triggerSource: true,
           ttl: true,
+          regions: true,
           queue: { select: { id: true, name: true } },
         },
       })
@@ -157,6 +158,7 @@ export class ChangeCurrentDeploymentService extends BaseService {
         triggerSource: t.triggerSource,
         queueId: t.queue?.id ?? null,
         queueName: t.queue?.name ?? "",
+        regions: t.regions,
       }));
 
       // Cache calls log+swallow internally.