fix(webapp,run-engine,core): treat an empty maxDelay as invalid and document the duration grammar

An empty string passed as maxDelay was falsy everywhere it was checked, so
it read as no ceiling at all rather than as the invalid value it is. The
server ceiling now also rejects zero and negative values at startup, and
the duration grammar in the errors and JSDoc lists the hr suffix and
compound forms that the parser has always accepted.

Author: matt-aitken

.changeset/debounce-max-duration.md

@@ -6,6 +6,8 @@ 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.
+
 ```ts
 await myTask.trigger(payload, {
   debounce: {

apps/webapp/app/env.server.ts

@@ -1041,7 +1041,7 @@ const EnvironmentSchema = z
      * bound. Setting this applies a ceiling to every debounced run that does not carry its own
      * `maxDelay`, and any `delay` at or above it stops runs from being pushed at all.
      */
-    RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS: z.coerce.number().int().optional(),
+    RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS: z.coerce.number().int().positive().optional(),
 
     /**
      * Bucket size in milliseconds used to quantize the newly computed `delayUntil`

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

@@ -140,7 +140,7 @@ export class RunEngineTriggerTaskService {
   #validateDebounceMaxDelay(
     debounce: NonNullable<NonNullable<TriggerTaskRequestBody["options"]>["debounce"]>
   ) {
-    if (!debounce.maxDelay) {
+    if (debounce.maxDelay === undefined) {
       return;
     }
 
@@ -149,7 +149,8 @@ export class RunEngineTriggerTaskService {
     if (maxDelayMs === undefined) {
       throw new ServiceValidationError(
         `Invalid debounce maxDelay: ${debounce.maxDelay}. ` +
-          `Supported formats: {number}s, {number}m, {number}h, {number}d, {number}w`
+          `Supported formats: {number}s, {number}m, {number}h or {number}hr, {number}d, {number}w, ` +
+          `optionally combined (for example "2h30m").`
       );
     }
 
@@ -306,7 +307,8 @@ export class RunEngineTriggerTaskService {
             if (debounceDelayError || !debounceDelayUntil) {
               throw new ServiceValidationError(
                 `Invalid debounce delay: ${body.options.debounce.delay}. ` +
-                  `Supported formats: {number}s, {number}m, {number}h, {number}d, {number}w`
+                  `Supported formats: {number}s, {number}m, {number}h or {number}hr, {number}d, ` +
+                  `{number}w, optionally combined (for example "2h30m").`
               );
             }
 

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

@@ -536,6 +536,17 @@ describe("RunEngineTriggerTaskService", () => {
         triggerWithDebounce({ key: "unparseable", delay: "10s", maxDelay: "soon" })
       ).rejects.toThrow(/Invalid debounce maxDelay/);
 
+      await expect(
+        triggerWithDebounce({ key: "empty", delay: "10s", maxDelay: "" })
+      ).rejects.toThrow(/Invalid debounce maxDelay/);
+
+      const compound = await triggerWithDebounce({
+        key: "compound",
+        delay: "2h30m",
+        maxDelay: "1d",
+      });
+      expect(compound?.run.friendlyId).toBeDefined();
+
       const withRoom = await triggerWithDebounce({
         key: "with-room",
         delay: "10s",

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

@@ -579,7 +579,7 @@ return 0
    * which is itself unset by default. An unparseable `maxDelay` falls back to the ceiling.
    */
   #resolveMaxDurationMs(debounce: DebounceOptions): number | undefined {
-    if (!debounce.maxDelay) {
+    if (debounce.maxDelay === undefined) {
       return this.maxDebounceDurationMs;
     }
 

packages/core/src/v3/types/tasks.ts

@@ -971,11 +971,14 @@ export type TriggerOptions = {
      * the new execution time stays inside `maxDelay`, so a `delay` at or above `maxDelay` leaves
      * no room to push and every trigger creates its own run.
      *
-     * Supported formats: `{number}s` (seconds), `{number}m` (minutes), `{number}h` (hours),
-     * `{number}d` (days), `{number}w` (weeks). Must be a duration, not a date. Minimum delay is
-     * 1 second.
+     * Must be a duration, not a date: the value is re-applied every time the run is pushed
+     * back, so an absolute date cannot work and debouncing silently stops collapsing.
      *
-     * @example "1s", "5s", "1m", "30m", "1h"
+     * Supported formats: `{number}s` (seconds), `{number}m` (minutes), `{number}h` or
+     * `{number}hr` (hours), `{number}d` (days), `{number}w` (weeks), optionally combined.
+     * Minimum delay is 1 second.
+     *
+     * @example "1s", "5s", "1m", "30m", "1h", "2h30m"
      */
     delay: string;
     /**
@@ -1001,10 +1004,10 @@ export type TriggerOptions = {
      * `maxDelay` of `"5m"` keeps extending for just under 5 minutes from the first trigger,
      * then runs.
      *
-     * Supported formats: `{number}s` (seconds), `{number}m` (minutes), `{number}h` (hours),
-     * `{number}d` (days), `{number}w` (weeks).
+     * Supported formats: `{number}s` (seconds), `{number}m` (minutes), `{number}h` or
+     * `{number}hr` (hours), `{number}d` (days), `{number}w` (weeks), optionally combined.
      *
-     * @example "30m", "2h", "1d"
+     * @example "30m", "2h", "1d", "2h30m"
      */
     maxDelay?: string;
   };