Support Long Timers ⏳📈🚀🚀🚀

src/actions/createtimeraction.ts

@@ -5,7 +5,7 @@ import { ActionType, IAction } from "../classes";
 export class CreateTimerAction implements IAction {
     public readonly actionType: ActionType = ActionType.CreateTimer;
 
-    constructor(public readonly fireAt: Date, public isCancelled: boolean = false) {
+    constructor(public readonly fireAt: Date, public isCanceled: boolean = false) {
         if (!isDate(fireAt)) {
             throw new TypeError(`fireAt: Expected valid Date object but got ${fireAt}`);
         }

src/durableorchestrationbindinginfo.ts

@@ -11,6 +11,8 @@ export class DurableOrchestrationBindingInfo {
         public readonly instanceId: string = "",
         public readonly isReplaying: boolean = false,
         public readonly parentInstanceId?: string,
+        public readonly maximumShortTimerDuration?: string,
+        public readonly longRunningTimerIntervalDuration?: string,
         upperSchemaVersion = 0 // TODO: Implement entity locking // public readonly contextLocks?: EntityId[],
     ) {
         // It is assumed that the extension supports all schemas in range [0, upperSchemaVersion].

src/durableorchestrationcontext.ts

@@ -28,7 +28,10 @@ import {
     Task,
     TimerTask,
     DFTask,
+    LongTimerTask,
 } from "./task";
+import moment = require("moment");
+import { ReplaySchema } from "./replaySchema";
 
 /**
  * Parameter data for orchestration bindings that can be used to schedule
@@ -41,6 +44,9 @@ export class DurableOrchestrationContext {
         currentUtcDateTime: Date,
         isReplaying: boolean,
         parentInstanceId: string | undefined,
+        longRunningTimerIntervalDuration: string | undefined,
+        maximumShortTimerDuration: string | undefined,
+        schemaVersion: ReplaySchema,
         input: unknown,
         private taskOrchestratorExecutor: TaskOrchestrationExecutor
     ) {
@@ -49,6 +55,13 @@ export class DurableOrchestrationContext {
         this.isReplaying = isReplaying;
         this.currentUtcDateTime = currentUtcDateTime;
         this.parentInstanceId = parentInstanceId;
+        this.longRunningTimerIntervalDuration = longRunningTimerIntervalDuration
+            ? moment.duration(longRunningTimerIntervalDuration)
+            : undefined;
+        this.maximumShortTimerDuration = maximumShortTimerDuration
+            ? moment.duration(maximumShortTimerDuration)
+            : undefined;
+        this.schemaVersion = schemaVersion;
         this.input = input;
         this.newGuidCounter = 0;
     }
@@ -101,6 +114,34 @@ export class DurableOrchestrationContext {
      */
     public currentUtcDateTime: Date;
 
+    /**
+     * Gets the maximum duration for timers allowed by the
+     * underlying storage infrastructure
+     *
+     * This duration property is determined by the underlying storage
+     * solution and passed to the SDK from the extension.
+     */
+    private readonly maximumShortTimerDuration: moment.Duration | undefined;
+
+    /**
+     * A duration property which defines the duration of smaller
+     * timers to break long timers into, in case they are longer
+     * than the maximum supported duration
+     *
+     * This duration property is determined by the underlying
+     * storage solution and passed to the SDK from the extension.
+     */
+    private readonly longRunningTimerIntervalDuration: moment.Duration | undefined;
+
+    /**
+     * Gets the current schema version that this execution is
+     * utilizing, based on negotiation with the extension.
+     *
+     * Different schema versions can allow different behavior.
+     * For example, long timers are only supported in schema version >=3
+     */
+    private readonly schemaVersion: ReplaySchema;
+
     /**
      * @hidden
      * This method informs the type-checker that an ITask[] can be treated as DFTask[].
@@ -293,9 +334,33 @@ export class DurableOrchestrationContext {
      * @returns A TimerTask that completes when the durable timer expires.
      */
     public createTimer(fireAt: Date): TimerTask {
-        const newAction = new CreateTimerAction(fireAt);
-        const task = new DFTimerTask(false, newAction);
-        return task;
+        const timerAction = new CreateTimerAction(fireAt);
+        const durationUntilFire = moment.duration(moment(fireAt).diff(this.currentUtcDateTime));
+        if (this.schemaVersion >= ReplaySchema.V3) {
+            if (!this.maximumShortTimerDuration || !this.longRunningTimerIntervalDuration) {
+                throw Error(
+                    "A framework-internal error was detected: replay schema version >= V3 is being used, " +
+                        "but one or more of the properties `maximumShortTimerDuration` and `longRunningTimerIntervalDuration` are not defined. " +
+                        "This is likely an issue with the Durable Functions Extension. " +
+                        "Please report this bug here: https://github.com/Azure/azure-functions-durable-js/issues\n" +
+                        `maximumShortTimerDuration: ${this.maximumShortTimerDuration}\n` +
+                        `longRunningTimerIntervalDuration: ${this.longRunningTimerIntervalDuration}`
+                );
+            }
+
+            if (durationUntilFire > this.maximumShortTimerDuration) {
+                return new LongTimerTask(
+                    false,
+                    timerAction,
+                    this,
+                    this.taskOrchestratorExecutor,
+                    this.maximumShortTimerDuration,
+                    this.longRunningTimerIntervalDuration
+                );
+            }
+        }
+
+        return new DFTimerTask(false, timerAction);
     }
 
     /**

src/orchestrator.ts

@@ -61,6 +61,9 @@ export class Orchestrator {
                 this.currentUtcDateTime,
                 orchestrationBinding.isReplaying,
                 orchestrationBinding.parentInstanceId,
+                orchestrationBinding.longRunningTimerIntervalDuration,
+                orchestrationBinding.maximumShortTimerDuration,
+                upperSchemaVersion,
                 input,
                 this.taskOrchestrationExecutor
             );

src/replaySchema.ts

@@ -5,6 +5,7 @@
 export enum ReplaySchema {
     V1 = 0,
     V2 = 1,
+    V3 = 2,
 }
 
-export const LatestReplaySchema: ReplaySchema = ReplaySchema.V2;
+export const LatestReplaySchema: ReplaySchema = ReplaySchema.V3;

src/task.ts

@@ -1,6 +1,8 @@
 import { RetryOptions } from ".";
 import { IAction, CreateTimerAction } from "./classes";
 import { TaskOrchestrationExecutor } from "./taskorchestrationexecutor";
+import moment = require("moment");
+import { DurableOrchestrationContext } from "./durableorchestrationcontext";
 
 /**
  * @hidden
@@ -16,7 +18,7 @@ export enum TaskState {
  * @hidden
  * A taskID, either a `string` for external events,
  * or either `false` or a `number` for un-awaited
- * an awaited tasks respectively.
+ * and awaited tasks respectively.
  */
 export type TaskID = number | string | false;
 
@@ -94,7 +96,7 @@ export interface TimerTask extends Task {
     /**
      * @returns Whether or not the timer has been canceled.
      */
-    isCancelled: boolean;
+    isCanceled: boolean;
     /**
      * Indicates the timer should be canceled. This request will execute on the
      * next `yield` or `return` statement.
@@ -291,8 +293,8 @@ export class DFTimerTask extends AtomicTask implements TimerTask {
     }
 
     /** Whether this timer task is cancelled */
-    get isCancelled(): boolean {
-        return this.action.isCancelled;
+    get isCanceled(): boolean {
+        return this.action.isCanceled;
     }
 
     /**
@@ -304,7 +306,7 @@ export class DFTimerTask extends AtomicTask implements TimerTask {
         if (this.hasResult) {
             throw Error("Cannot cancel a completed task.");
         }
-        this.action.isCancelled = true; // TODO: fix typo
+        this.action.isCanceled = true;
     }
 }
 
@@ -377,6 +379,103 @@ export class WhenAnyTask extends CompoundTask {
     }
 }
 
+/**
+ * @hidden
+ *
+ * A long Timer Task.
+ *
+ * This Task is created when a timer is created with a duration
+ * longer than the maximum timer duration supported by storage infrastructure.
+ *
+ * It extends `WhenAllTask` because it decomposes into
+ * several smaller sub-`TimerTask`s
+ */
+export class LongTimerTask extends WhenAllTask implements TimerTask {
+    public id: TaskID;
+    public action: CreateTimerAction;
+    private readonly executor: TaskOrchestrationExecutor;
+    private readonly maximumTimerLength: moment.Duration;
+    private readonly orchestrationContext: DurableOrchestrationContext;
+    private readonly longRunningTimerIntervalDuration: moment.Duration;
+
+    public constructor(
+        id: TaskID,
+        action: CreateTimerAction,
+        orchestrationContext: DurableOrchestrationContext,
+        executor: TaskOrchestrationExecutor,
+        maximumTimerLength: moment.Duration,
+        longRunningTimerIntervalDuration: moment.Duration
+    ) {
+        const currentTime = orchestrationContext.currentUtcDateTime;
+        const finalFireTime = action.fireAt;
+        const durationUntilFire = moment.duration(moment(finalFireTime).diff(currentTime));
+
+        const nextFireTime: Date =
+            durationUntilFire > maximumTimerLength
+                ? moment(currentTime).add(longRunningTimerIntervalDuration).toDate()
+                : finalFireTime;
+
+        const nextTimerAction = new CreateTimerAction(nextFireTime);
+        const nextTimerTask = new DFTimerTask(false, nextTimerAction);
+        super([nextTimerTask], action);
+
+        this.id = id;
+        this.action = action;
+        this.orchestrationContext = orchestrationContext;
+        this.executor = executor;
+        this.maximumTimerLength = maximumTimerLength;
+        this.longRunningTimerIntervalDuration = longRunningTimerIntervalDuration;
+    }
+
+    get isCanceled(): boolean {
+        return this.action.isCanceled;
+    }
+
+    /**
+     * @hidden
+     * Cancel this timer task.
+     * It errors out if the task has already completed.
+     */
+    public cancel(): void {
+        if (this.hasResult) {
+            throw Error("Cannot cancel a completed task.");
+        }
+        this.action.isCanceled = true;
+    }
+
+    /**
+     * @hidden
+     * Attempts to set a value to this timer, given a completed sub-timer
+     *
+     * @param child
+     * The sub-timer that just completed
+     */
+    public trySetValue(child: DFTimerTask): void {
+        const currentTime = this.orchestrationContext.currentUtcDateTime;
+        const finalFireTime = this.action.fireAt;
+        if (finalFireTime > currentTime) {
+            const nextTimer: DFTimerTask = this.getNextTimerTask(finalFireTime, currentTime);
+            this.addNewChild(nextTimer);
+        }
+        super.trySetValue(child);
+    }
+
+    private getNextTimerTask(finalFireTime: Date, currentTime: Date): DFTimerTask {
+        const durationUntilFire = moment.duration(moment(finalFireTime).diff(currentTime));
+        const nextFireTime: Date =
+            durationUntilFire > this.maximumTimerLength
+                ? moment(currentTime).add(this.longRunningTimerIntervalDuration).toDate()
+                : finalFireTime;
+        return new DFTimerTask(false, new CreateTimerAction(nextFireTime));
+    }
+
+    private addNewChild(childTimer: DFTimerTask): void {
+        childTimer.parent = this;
+        this.children.push(childTimer);
+        this.executor.trackOpenTask(childTimer);
+    }
+}
+
 /**
  * @hidden
  *

src/testingUtils.ts

@@ -16,6 +16,7 @@ import {
     OrchestratorStartedEvent,
 } from "./classes";
 import { IOrchestrationFunctionContext } from "./iorchestrationfunctioncontext";
+import { ReplaySchema } from "./replaySchema";
 import { TaskOrchestrationExecutor } from "./taskorchestrationexecutor";
 
 /**
@@ -33,13 +34,19 @@ export class DummyOrchestrationContext implements IOrchestrationFunctionContext
      * @param input The input to the orchestration
      * @param currentUtcDateTime The deterministic date at the beginning of orchestration replay
      * @param isReplaying Whether the orchestration is to be marked as isReplaying the its first event
+     * @param longRunningTimerIntervalDuration The duration to break smaller timers into if a long timer exceeds the maximum allowed duration
+     * @param maximumShortTimerDuration The maximum duration for a timer allowed by the underlying storage infrastructure
+     * @param schemaVersion The schema version currently used after being negotiated with the extension
      * @param parentInstanceId The instanceId of the orchestration's parent, if this is a sub-orchestration
      */
     constructor(
         instanceId = "",
         history: HistoryEvent[] | undefined = undefined,
         input: any = undefined,
         currentUtcDateTime: Date = new Date(),
+        longRunningTimerIntervalDuration: string,
+        maximumShortTimerDuration: string,
+        schemaVersion: ReplaySchema,
         isReplaying = false,
         parentInstanceId = ""
     ) {
@@ -54,6 +61,9 @@ export class DummyOrchestrationContext implements IOrchestrationFunctionContext
             currentUtcDateTime,
             isReplaying,
             parentInstanceId,
+            longRunningTimerIntervalDuration,
+            maximumShortTimerDuration,
+            schemaVersion,
             input,
             new TaskOrchestrationExecutor()
         );

src/utils.ts

@@ -19,9 +19,6 @@ export class Utils {
                 this.hasAllPropertiesOf(value, typeInstance)
             );
 
-            // This recursive step ensures _all_ Timestamp properties are converted properly
-            // For example, a payload can contain the history as a property, so if we want to
-            // parse each HistoryEvent's Timestamp, we need to traverse the payload recursively
             this.parseTimestampsAsDates(candidateObjects);
 
             return candidateObjects as T[];
@@ -60,6 +57,9 @@ export class Utils {
                 obj.Timestamp = new Date(obj.Timestamp);
             }
             Object.values(obj).map((value) => {
+                // This recursive step ensures _all_ Timestamp properties are converted properly
+                // For example, a payload can contain the history as a property, so if we want to
+                // parse each HistoryEvent's Timestamp, we need to traverse the payload recursively
                 this.parseTimestampsAsDates(value);
             });
         }