fix(webapp): reject debounce windows that cannot collapse anything

Validation only looked at a caller-supplied maxDelay, so a deployment
that configures a server ceiling kept the original silent failure: a
delay at or above it accepted the trigger and then created a run per
trigger. The check now runs against the effective ceiling, whichever of
the two applies, and a delay given as a date is rejected as well since
the value is re-applied on every push and an absolute date can never
work.

Author: matt-aitken

.changeset/debounce-max-duration.md

@@ -6,7 +6,7 @@ Debouncing with a `delay` longer than an hour now works. A hidden server-side li
 
 That limit is gone. A debounce key with no `maxDelay` now keeps pushing its run back for as long as triggers keep arriving, which means it never executes while they do. Set `maxDelay` when the work has to happen eventually, and keep `delay` well below it, since the room available to push is the gap between the two.
 
-Triggers that set a `maxDelay` no longer than their `delay` are now rejected, as are unparseable `maxDelay` values. Both previously went through and left debouncing doing nothing.
+Triggers we know cannot debounce are now rejected instead of quietly doing nothing: a `maxDelay` no longer than the `delay`, an unparseable `maxDelay`, and a `delay` given as a date rather than a duration. Self-hosters who configure a maximum debounce duration get the same treatment for a `delay` at or above it.
 
 ```ts
 await myTask.trigger(payload, {

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

@@ -7,6 +7,7 @@ import type { Tracer } from "@opentelemetry/api";
 import { tryCatch } from "@trigger.dev/core/utils";
 import {
   type TriggerTaskRequestBody,
+  formatDurationMilliseconds,
   RunAnnotations,
   TaskRunError,
   taskRunErrorEnhancer,
@@ -90,6 +91,7 @@ export class RunEngineTriggerTaskService {
   private readonly traceEventConcern: TraceEventConcern;
   private readonly triggerRacepointSystem: TriggerRacepointSystem;
   private readonly metadataMaximumSize: number;
+  private readonly maximumDebounceDurationMs: number | undefined;
   // Mollifier hooks are DI'd so tests can drive the call-site's mollify branch
   // deterministically (stub the gate to return mollify, inject a real or fake
   // buffer, force the global-enabled predicate to true so the call site
@@ -109,6 +111,7 @@ export class RunEngineTriggerTaskService {
     traceEventConcern: TraceEventConcern;
     tracer: Tracer;
     metadataMaximumSize: number;
+    maximumDebounceDurationMs?: number;
     triggerRacepointSystem?: TriggerRacepointSystem;
     evaluateGate?: MollifierEvaluateGate;
     getMollifierBuffer?: MollifierGetBuffer;
@@ -123,6 +126,8 @@ export class RunEngineTriggerTaskService {
     this.tracer = opts.tracer;
     this.traceEventConcern = opts.traceEventConcern;
     this.metadataMaximumSize = opts.metadataMaximumSize;
+    this.maximumDebounceDurationMs =
+      opts.maximumDebounceDurationMs ?? env.RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS;
     this.triggerRacepointSystem = opts.triggerRacepointSystem ?? new NoopTriggerRacepointSystem();
     this.evaluateGate = opts.evaluateGate ?? defaultEvaluateGate;
     this.getMollifierBuffer = opts.getMollifierBuffer ?? defaultGetMollifierBuffer;
@@ -131,36 +136,60 @@ export class RunEngineTriggerTaskService {
   }
 
   /**
-   * A debounced run is only pushed back while its new execution time stays inside `maxDelay`,
-   * so the room available to push is `maxDelay` minus `delay`. When a caller sets both and
-   * leaves no room, the debounce key silently does nothing and every trigger creates its own
-   * run, which is worse than being told. Only an explicit `maxDelay` is checked; with no
-   * `maxDelay` there is no ceiling to conflict with.
+   * A debounced run is only pushed back while its new execution time stays inside the effective
+   * ceiling, which is the trigger's own `maxDelay` or, failing that, whatever ceiling the server
+   * is configured with. The room available to push is that ceiling minus `delay`, so a `delay`
+   * at or above it leaves none: the debounce key does nothing and every trigger creates its own
+   * run. Rejecting is better than accepting a trigger we know cannot debounce.
+   *
+   * With no `maxDelay` and no server ceiling there is nothing to conflict with, which is the
+   * default.
    */
-  #validateDebounceMaxDelay(
+  #validateDebounceWindow(
     debounce: NonNullable<NonNullable<TriggerTaskRequestBody["options"]>["debounce"]>
   ) {
-    if (debounce.maxDelay === undefined) {
-      return;
-    }
-
-    const maxDelayMs = parseNaturalLanguageDurationInMs(debounce.maxDelay);
+    const delayMs = parseNaturalLanguageDurationInMs(debounce.delay);
 
-    if (maxDelayMs === undefined) {
+    if (delayMs === undefined) {
       throw new ServiceValidationError(
-        `Invalid debounce maxDelay: ${debounce.maxDelay}. ` +
-          `Supported formats: {number}s, {number}m, {number}h or {number}hr, {number}d, {number}w, ` +
-          `optionally combined (for example "2h30m").`
+        `Invalid debounce delay: ${debounce.delay}. debounce.delay must be a duration, not a ` +
+          `date, because it is re-applied every time the run is pushed back. Supported formats: ` +
+          `{number}s, {number}m, {number}h or {number}hr, {number}d, {number}w, optionally ` +
+          `combined (for example "2h30m").`
       );
     }
 
-    const delayMs = parseNaturalLanguageDurationInMs(debounce.delay);
+    if (debounce.maxDelay !== undefined) {
+      const maxDelayMs = parseNaturalLanguageDurationInMs(debounce.maxDelay);
+
+      if (maxDelayMs === undefined) {
+        throw new ServiceValidationError(
+          `Invalid debounce maxDelay: ${debounce.maxDelay}. ` +
+            `Supported formats: {number}s, {number}m, {number}h or {number}hr, {number}d, ` +
+            `{number}w, optionally combined (for example "2h30m").`
+        );
+      }
+
+      if (maxDelayMs <= delayMs) {
+        throw new ServiceValidationError(
+          `debounce.maxDelay (${debounce.maxDelay}) must be longer than debounce.delay ` +
+            `(${debounce.delay}). A debounced run is only pushed back while it stays inside ` +
+            `maxDelay, so with these values every trigger would create its own run.`
+        );
+      }
+
+      return;
+    }
+
+    const serverCeilingMs = this.maximumDebounceDurationMs;
 
-    if (delayMs !== undefined && maxDelayMs <= delayMs) {
+    if (serverCeilingMs !== undefined && delayMs >= serverCeilingMs) {
       throw new ServiceValidationError(
-        `debounce.maxDelay (${debounce.maxDelay}) must be longer than debounce.delay (${debounce.delay}). ` +
-          `A debounced run is only pushed back while it stays inside maxDelay, so with these values ` +
-          `every trigger would create its own run.`
+        `debounce.delay (${debounce.delay}) is at or above this server's maximum debounce ` +
+          `duration of ${formatDurationMilliseconds(serverCeilingMs, { style: "short" })}. A ` +
+          `debounced run is only pushed back while it stays inside that window, so with this ` +
+          `delay every trigger would create its own run. Either shorten the delay, or set ` +
+          `debounce.maxDelay above ${debounce.delay}.`
       );
     }
   }
@@ -312,7 +341,7 @@ export class RunEngineTriggerTaskService {
               );
             }
 
-            this.#validateDebounceMaxDelay(body.options.debounce);
+            this.#validateDebounceWindow(body.options.debounce);
           }
 
           const parentRun = body.options?.parentRunId

apps/webapp/test/engine/triggerTask.debounce.test.ts

@@ -556,6 +556,54 @@ describe("RunEngineTriggerTaskService", () => {
 
       const noMaxDelay = await triggerWithDebounce({ key: "no-max-delay", delay: "12h" });
       expect(noMaxDelay?.run.friendlyId).toBeDefined();
+
+      await expect(
+        triggerWithDebounce({ key: "date-delay", delay: "2027-01-01T00:00:00.000Z" })
+      ).rejects.toThrow(/must be a duration, not a date/);
+
+      const withServerCeiling = new RunEngineTriggerTaskService({
+        engine,
+        prisma,
+        payloadProcessor: new MockPayloadProcessor(),
+        queueConcern: queuesManager,
+        idempotencyKeyConcern,
+        validator: new MockTriggerTaskValidator(),
+        traceEventConcern: new MockTraceEventConcern(),
+        tracer: trace.getTracer("test", "0.0.0"),
+        metadataMaximumSize: 1024 * 1024 * 1,
+        maximumDebounceDurationMs: 60 * 60 * 1000,
+      });
+
+      await expect(
+        withServerCeiling.call({
+          taskId: taskIdentifier,
+          environment: authenticatedEnvironment,
+          body: {
+            payload: { test: "test" },
+            options: { debounce: { key: "over-server-ceiling", delay: "12h" } },
+          },
+        })
+      ).rejects.toThrow(/at or above this server's maximum debounce duration of 1h/);
+
+      const underServerCeiling = await withServerCeiling.call({
+        taskId: taskIdentifier,
+        environment: authenticatedEnvironment,
+        body: {
+          payload: { test: "test" },
+          options: { debounce: { key: "under-server-ceiling", delay: "10s" } },
+        },
+      });
+      expect(underServerCeiling?.run.friendlyId).toBeDefined();
+
+      const overCeilingWithMaxDelay = await withServerCeiling.call({
+        taskId: taskIdentifier,
+        environment: authenticatedEnvironment,
+        body: {
+          payload: { test: "test" },
+          options: { debounce: { key: "override", delay: "12h", maxDelay: "24h" } },
+        },
+      });
+      expect(overCeilingWithMaxDelay?.run.friendlyId).toBeDefined();
     }
   );
 });

docs/triggering.mdx

@@ -928,7 +928,7 @@ Consider `delay: "5s"` and `maxDelay: "30s"` with triggers arriving every 2 seco
 
 Without `maxDelay`, continuous triggers would prevent the run from ever executing. With `maxDelay: "30s"`, execution is guaranteed within 30 seconds of the first trigger.
 
-Keep `delay` well below `maxDelay`. A run is only pushed back while its new execution time stays inside `maxDelay`, so the room you have to push is `maxDelay` minus `delay`. Setting them equal, or setting `delay` higher, leaves no room at all: every trigger creates its own run and the debounce key has no effect.
+Keep `delay` well below `maxDelay`. A run is only pushed back while its new execution time stays inside `maxDelay`, so the room you have to push is `maxDelay` minus `delay`. Setting them equal, or setting `delay` higher, leaves no room at all, and the trigger is rejected rather than accepted as a debounce that could never collapse anything.
 
 <Note>
   The `maxDelay` value is evaluated from each trigger call, not stored with the original run. This