refactor(run-engine,webapp): one shared gate parser with tests

The webapp and the enqueue system carried identical copies of the gate
contract with nothing enforcing their parity. parseGates now lives in
the run-engine package with unit tests covering every rule (bounds kept
inclusive at 128, empty keys inherit, malformed entries dropped, capped
at two), and both callers delegate to it.

Author: matt-aitken

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

@@ -1,4 +1,5 @@
 import type { Redis, Result, Callback } from "ioredis";
+import { parseGates } from "@internal/run-engine";
 import type { TaskTriggerSource } from "@trigger.dev/database";
 import { logger } from "./logger.server";
 
@@ -61,27 +62,8 @@ export type RedisTaskMetadataCacheOptions = {
  * entries so a malformed value can never fail a trigger.
  */
 export function parseTaskGates(gates: unknown): TaskMetadataGate[] | null {
-  if (!Array.isArray(gates) || gates.length === 0) {
-    return null;
-  }
-
-  const parsed = gates.flatMap((gate) => {
-    if (!gate || typeof gate !== "object" || typeof (gate as any).queue !== "string") {
-      return [];
-    }
-    const queue = (gate as any).queue;
-    if (queue.length === 0 || queue.length > 128) {
-      return [];
-    }
-    const rawKey = (gate as any).concurrencyKey;
-    if (typeof rawKey === "string" && rawKey.length > 128) {
-      return [];
-    }
-    const concurrencyKey = typeof rawKey === "string" && rawKey.length > 0 ? rawKey : undefined;
-    return [{ queue, concurrencyKey }];
-  });
-
-  return parsed.length > 0 ? parsed.slice(0, 2) : null;
+  const parsed = parseGates(gates);
+  return parsed.length > 0 ? parsed : null;
 }
 
 type EncodedEntry = {

internal-packages/run-engine/src/engine/gateParsing.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { parseGates } from "./gateParsing.js";
+
+describe("parseGates", () => {
+  it("keeps well-shaped gates and caps at two", () => {
+    expect(
+      parseGates([{ queue: "a" }, { queue: "b", concurrencyKey: "shared" }, { queue: "c" }])
+    ).toEqual([
+      { queue: "a", concurrencyKey: undefined },
+      { queue: "b", concurrencyKey: "shared" },
+    ]);
+  });
+
+  it("returns empty for non-arrays and empty arrays", () => {
+    expect(parseGates(undefined)).toEqual([]);
+    expect(parseGates(null)).toEqual([]);
+    expect(parseGates("gates")).toEqual([]);
+    expect(parseGates([])).toEqual([]);
+  });
+
+  it("drops malformed entries", () => {
+    expect(parseGates([null, "x", 4, { concurrencyKey: "k" }, { queue: 7 }])).toEqual([]);
+  });
+
+  it("drops empty and over-length queue names, keeping exactly 128", () => {
+    const max = "q".repeat(128);
+    expect(parseGates([{ queue: "" }, { queue: "q".repeat(129) }, { queue: max }])).toEqual([
+      { queue: max, concurrencyKey: undefined },
+    ]);
+  });
+
+  it("treats an empty-string key as omitted and keeps exactly 128-char keys", () => {
+    const maxKey = "k".repeat(128);
+    expect(parseGates([{ queue: "a", concurrencyKey: "" }])).toEqual([
+      { queue: "a", concurrencyKey: undefined },
+    ]);
+    expect(parseGates([{ queue: "a", concurrencyKey: maxKey }])).toEqual([
+      { queue: "a", concurrencyKey: maxKey },
+    ]);
+  });
+
+  it("drops gates whose literal key exceeds the cap", () => {
+    expect(parseGates([{ queue: "a", concurrencyKey: "k".repeat(129) }, { queue: "b" }])).toEqual([
+      { queue: "b", concurrencyKey: undefined },
+    ]);
+  });
+
+  it("ignores non-string keys", () => {
+    expect(parseGates([{ queue: "a", concurrencyKey: 5 }])).toEqual([
+      { queue: "a", concurrencyKey: undefined },
+    ]);
+  });
+});

internal-packages/run-engine/src/engine/gateParsing.ts

@@ -0,0 +1,33 @@
+/**
+ * The gate contract for stored/untyped gate values (BackgroundWorkerTask.gates,
+ * TaskRun.gates are Json columns): keep only well-shaped entries so a malformed
+ * value can never fail a trigger or an enqueue. A gate needs a queue name within
+ * the manifest bounds (1-128 chars); a literal concurrency key must fit the same
+ * bounds, and an empty-string key means "omitted" so the gate inherits the run's
+ * key. At most two gates apply.
+ */
+export type ParsedGate = { queue: string; concurrencyKey?: string };
+
+export function parseGates(gates: unknown): ParsedGate[] {
+  if (!Array.isArray(gates) || gates.length === 0) {
+    return [];
+  }
+
+  const parsed = gates.flatMap((gate): ParsedGate[] => {
+    if (!gate || typeof gate !== "object" || typeof (gate as any).queue !== "string") {
+      return [];
+    }
+    const queue = (gate as any).queue;
+    if (queue.length === 0 || queue.length > 128) {
+      return [];
+    }
+    const rawKey = (gate as any).concurrencyKey;
+    if (typeof rawKey === "string" && rawKey.length > 128) {
+      return [];
+    }
+    const concurrencyKey = typeof rawKey === "string" && rawKey.length > 0 ? rawKey : undefined;
+    return [{ queue, concurrencyKey }];
+  });
+
+  return parsed.slice(0, 2);
+}

internal-packages/run-engine/src/engine/systems/enqueueSystem.ts

@@ -8,6 +8,7 @@ import type { RunStore } from "@internal/run-store";
 import { parseNaturalLanguageDuration } from "@trigger.dev/core/v3/isomorphic";
 import type { MinimalAuthenticatedEnvironment } from "../../shared/index.js";
 import { QUEUED_SNAPSHOT_DESCRIPTION, QUEUED_SNAPSHOT_STATUS } from "../consts.js";
+import { parseGates } from "../gateParsing.js";
 import type { ExecutionSnapshotSystem } from "./executionSnapshotSystem.js";
 import type { SystemResources } from "./systems.js";
 
@@ -16,34 +17,11 @@ export type EnqueueSystemOptions = {
   executionSnapshotSystem: ExecutionSnapshotSystem;
 };
 
-/**
- * TaskRun.gates is an untyped Json column; admit correctness only needs well-shaped
- * entries, so anything malformed is dropped rather than failing the enqueue.
- */
 function parseRunGates(
   gates: unknown
 ): Array<{ queue: string; concurrencyKey?: string }> | undefined {
-  if (!Array.isArray(gates) || gates.length === 0) {
-    return undefined;
-  }
-
-  const parsed = gates.flatMap((gate) => {
-    if (!gate || typeof gate !== "object" || typeof (gate as any).queue !== "string") {
-      return [];
-    }
-    const queue = (gate as any).queue;
-    if (queue.length === 0 || queue.length > 128) {
-      return [];
-    }
-    const rawKey = (gate as any).concurrencyKey;
-    if (typeof rawKey === "string" && rawKey.length > 128) {
-      return [];
-    }
-    const concurrencyKey = typeof rawKey === "string" && rawKey.length > 0 ? rawKey : undefined;
-    return [{ queue, concurrencyKey }];
-  });
-
-  return parsed.length > 0 ? parsed.slice(0, 2) : undefined;
+  const parsed = parseGates(gates);
+  return parsed.length > 0 ? parsed : undefined;
 }
 
 export class EnqueueSystem {

internal-packages/run-engine/src/index.ts

@@ -61,3 +61,4 @@ export type {
   WatcherEntry,
 } from "./engine/waitpointCoordinator/storeCoordinator.js";
 export { WaitpointKeyTagError } from "./engine/waitpointCoordinator/keys.js";
+export { parseGates, type ParsedGate } from "./engine/gateParsing.js";