feat: Enhance retry mechanism with failure handling and context

Author: YunchuWang

packages/durabletask-js/src/index.ts

@@ -62,18 +62,36 @@ export {
 // Proto types (for advanced usage)
 export { OrchestrationStatus as ProtoOrchestrationStatus } from "./proto/orchestrator_service_pb";
 
+// Failure details
+export { FailureDetails, TaskFailureDetails } from "./task/failure-details";
+
 // Task utilities
 export { getName, whenAll, whenAny } from "./task";
 export { Task } from "./task/task";
 
 // Retry policies and task options
-export { RetryPolicy, RetryPolicyOptions } from "./task/retry";
+export {
+  RetryPolicy,
+  RetryPolicyOptions,
+  FailureHandlerPredicate,
+  RetryContext,
+  createRetryContext,
+  RetryHandler,
+  AsyncRetryHandler,
+  toAsyncRetryHandler,
+} from "./task/retry";
 export {
   TaskOptions,
   SubOrchestrationOptions,
   StartOrchestrationOptions,
+  TaskRetryOptions,
   taskOptionsFromRetryPolicy,
+  taskOptionsFromRetryHandler,
+  taskOptionsFromSyncRetryHandler,
   subOrchestrationOptionsFromRetryPolicy,
+  subOrchestrationOptionsFromRetryHandler,
+  isRetryPolicy,
+  isAsyncRetryHandler,
 } from "./task/options";
 
 // Types

packages/durabletask-js/src/task/failure-details.ts

@@ -1,7 +1,20 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-export class FailureDetails {
+/**
+ * Interface representing task failure details.
+ * This is used for retry handlers to inspect failure information.
+ */
+export interface TaskFailureDetails {
+  /** The type/class name of the error */
+  readonly errorType: string;
+  /** The error message */
+  readonly message: string;
+  /** The stack trace, if available */
+  readonly stackTrace?: string;
+}
+
+export class FailureDetails implements TaskFailureDetails {
   private _message: string;
   private _errorType: string;
   private _stackTrace: string | undefined;

packages/durabletask-js/src/task/options/index.ts

@@ -5,6 +5,12 @@ export {
   TaskOptions,
   SubOrchestrationOptions,
   StartOrchestrationOptions,
+  TaskRetryOptions,
   taskOptionsFromRetryPolicy,
+  taskOptionsFromRetryHandler,
+  taskOptionsFromSyncRetryHandler,
   subOrchestrationOptionsFromRetryPolicy,
+  subOrchestrationOptionsFromRetryHandler,
+  isRetryPolicy,
+  isAsyncRetryHandler,
 } from "./task-options";

packages/durabletask-js/src/task/options/task-options.ts

@@ -2,16 +2,23 @@
 // Licensed under the MIT License.
 
 import { RetryPolicy } from "../retry/retry-policy";
+import { AsyncRetryHandler, RetryHandler, toAsyncRetryHandler } from "../retry/retry-handler";
+
+/**
+ * Union type representing either a RetryPolicy for declarative retry or an AsyncRetryHandler for imperative retry.
+ */
+export type TaskRetryOptions = RetryPolicy | AsyncRetryHandler;
 
 /**
  * Options that can be used to control the behavior of orchestrator task execution.
  */
 export interface TaskOptions {
   /**
-   * The retry policy for the task.
-   * Controls how many times a task is retried and the delay between retries.
+   * The retry options for the task.
+   * Can be either a RetryPolicy for declarative retry control,
+   * or an AsyncRetryHandler for imperative (programmatic) retry control.
    */
-  retry?: RetryPolicy;
+  retry?: TaskRetryOptions;
   /**
    * The tags to associate with the task.
    */
@@ -81,6 +88,48 @@ export function taskOptionsFromRetryPolicy(policy: RetryPolicy): TaskOptions {
   return { retry: policy };
 }
 
+/**
+ * Creates a TaskOptions instance from an AsyncRetryHandler.
+ *
+ * @param handler - The async retry handler to use
+ * @returns A TaskOptions instance configured with the retry handler
+ *
+ * @example
+ * ```typescript
+ * const handler: AsyncRetryHandler = async (context) => {
+ *   if (context.lastAttemptNumber >= 5) return false;
+ *   if (context.lastFailure.errorType === "ValidationError") return false;
+ *   return true;
+ * };
+ *
+ * const options = taskOptionsFromRetryHandler(handler);
+ * await ctx.callActivity("myActivity", input, options);
+ * ```
+ */
+export function taskOptionsFromRetryHandler(handler: AsyncRetryHandler): TaskOptions {
+  return { retry: handler };
+}
+
+/**
+ * Creates a TaskOptions instance from a synchronous RetryHandler.
+ *
+ * @param handler - The sync retry handler to use (will be wrapped in a Promise)
+ * @returns A TaskOptions instance configured with the retry handler
+ *
+ * @example
+ * ```typescript
+ * const handler: RetryHandler = (context) => {
+ *   return context.lastAttemptNumber < 3;
+ * };
+ *
+ * const options = taskOptionsFromSyncRetryHandler(handler);
+ * await ctx.callActivity("myActivity", input, options);
+ * ```
+ */
+export function taskOptionsFromSyncRetryHandler(handler: RetryHandler): TaskOptions {
+  return { retry: toAsyncRetryHandler(handler) };
+}
+
 /**
  * Creates a SubOrchestrationOptions instance from a RetryPolicy and optional instance ID.
  *
@@ -104,3 +153,46 @@ export function subOrchestrationOptionsFromRetryPolicy(
 ): SubOrchestrationOptions {
   return { retry: policy, instanceId };
 }
+
+/**
+ * Creates a SubOrchestrationOptions instance from an AsyncRetryHandler and optional instance ID.
+ *
+ * @param handler - The async retry handler to use
+ * @param instanceId - Optional instance ID for the sub-orchestration
+ * @returns A SubOrchestrationOptions instance configured with the retry handler
+ *
+ * @example
+ * ```typescript
+ * const handler: AsyncRetryHandler = async (context) => {
+ *   return context.lastAttemptNumber < 3;
+ * };
+ *
+ * const options = subOrchestrationOptionsFromRetryHandler(handler, "my-sub-orch-123");
+ * ```
+ */
+export function subOrchestrationOptionsFromRetryHandler(
+  handler: AsyncRetryHandler,
+  instanceId?: string,
+): SubOrchestrationOptions {
+  return { retry: handler, instanceId };
+}
+
+/**
+ * Type guard to check if the retry option is a RetryPolicy.
+ *
+ * @param retry - The retry option to check
+ * @returns true if the retry option is a RetryPolicy, false otherwise
+ */
+export function isRetryPolicy(retry: TaskRetryOptions | undefined): retry is RetryPolicy {
+  return retry instanceof RetryPolicy;
+}
+
+/**
+ * Type guard to check if the retry option is an AsyncRetryHandler.
+ *
+ * @param retry - The retry option to check
+ * @returns true if the retry option is an AsyncRetryHandler, false otherwise
+ */
+export function isAsyncRetryHandler(retry: TaskRetryOptions | undefined): retry is AsyncRetryHandler {
+  return typeof retry === "function";
+}

packages/durabletask-js/src/task/retry/index.ts

@@ -1,4 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-export { RetryPolicy, RetryPolicyOptions } from "./retry-policy";
+export { RetryPolicy, RetryPolicyOptions, FailureHandlerPredicate } from "./retry-policy";
+export { RetryContext, createRetryContext } from "./retry-context";
+export { RetryHandler, AsyncRetryHandler, toAsyncRetryHandler } from "./retry-handler";

packages/durabletask-js/src/task/retry/retry-context.ts

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { TaskFailureDetails } from "../failure-details";
+
+/**
+ * Retry context data that's provided to task retry handler implementations.
+ *
+ * @remarks
+ * This context is passed to custom retry handlers to provide information about
+ * the current retry state and allow making informed decisions about whether
+ * to continue retrying.
+ *
+ * Retry handler code is an extension of the orchestrator code and must therefore
+ * comply with all the determinism requirements of orchestrator code.
+ *
+ * @example
+ * ```typescript
+ * const retryHandler: RetryHandler = (context: RetryContext) => {
+ *   // Don't retry after 5 attempts
+ *   if (context.lastAttemptNumber >= 5) {
+ *     return false;
+ *   }
+ *   // Don't retry if we've been retrying for more than 5 minutes
+ *   if (context.totalRetryTimeInMilliseconds > 300000) {
+ *     return false;
+ *   }
+ *   // Don't retry certain error types
+ *   if (context.lastFailure.errorType === "ValidationError") {
+ *     return false;
+ *   }
+ *   return true;
+ * };
+ * ```
+ */
+export interface RetryContext {
+  /**
+   * The previous retry attempt number.
+   * This is 1 after the first failure, 2 after the second, etc.
+   */
+  readonly lastAttemptNumber: number;
+
+  /**
+   * The details of the previous task failure.
+   * Contains the error type, message, and stack trace.
+   */
+  readonly lastFailure: TaskFailureDetails;
+
+  /**
+   * The total amount of time spent in the retry loop for the current task, in milliseconds.
+   * This includes the time spent executing the task and waiting between retries.
+   */
+  readonly totalRetryTimeInMilliseconds: number;
+
+  /**
+   * Whether the retry operation has been cancelled.
+   * Handlers should check this and return false if cancellation is requested.
+   */
+  readonly isCancelled: boolean;
+}
+
+/**
+ * Creates a new RetryContext object.
+ *
+ * @param lastAttemptNumber - The previous retry attempt number
+ * @param lastFailure - The details of the previous task failure
+ * @param totalRetryTimeInMilliseconds - The total time spent retrying
+ * @param isCancelled - Whether cancellation has been requested
+ * @returns A RetryContext object
+ */
+export function createRetryContext(
+  lastAttemptNumber: number,
+  lastFailure: TaskFailureDetails,
+  totalRetryTimeInMilliseconds: number,
+  isCancelled: boolean = false,
+): RetryContext {
+  return {
+    lastAttemptNumber,
+    lastFailure,
+    totalRetryTimeInMilliseconds,
+    isCancelled,
+  };
+}

packages/durabletask-js/src/task/retry/retry-handler.ts

@@ -0,0 +1,91 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { RetryContext } from "./retry-context";
+
+/**
+ * Delegate for manually handling task retries (synchronous version).
+ *
+ * @remarks
+ * Retry handler code is an extension of the orchestrator code and must therefore
+ * comply with all the determinism requirements of orchestrator code. This means:
+ * - No I/O operations (file, network, database)
+ * - No random number generation
+ * - No accessing current date/time directly
+ * - No accessing environment variables
+ *
+ * @param retryContext - Retry context that's updated between each retry attempt
+ * @returns Returns `true` to continue retrying or `false` to stop retrying
+ *
+ * @example
+ * ```typescript
+ * const handler: RetryHandler = (context) => {
+ *   // Retry up to 5 times
+ *   if (context.lastAttemptNumber >= 5) {
+ *     return false;
+ *   }
+ *   // Don't retry validation errors
+ *   if (context.lastFailure.errorType === "ValidationError") {
+ *     return false;
+ *   }
+ *   return true;
+ * };
+ *
+ * const options = taskOptionsFromRetryHandler(handler);
+ * await ctx.callActivity("myActivity", input, options);
+ * ```
+ */
+export type RetryHandler = (retryContext: RetryContext) => boolean;
+
+/**
+ * Delegate for manually handling task retries (asynchronous version).
+ *
+ * @remarks
+ * Retry handler code is an extension of the orchestrator code and must therefore
+ * comply with all the determinism requirements of orchestrator code. This means:
+ * - No I/O operations (file, network, database)
+ * - No random number generation
+ * - No accessing current date/time directly
+ * - No accessing environment variables
+ *
+ * While this handler is async, the async operations should only be used for
+ * deterministic orchestration operations (like waiting for events or timers),
+ * not for non-deterministic I/O.
+ *
+ * @param retryContext - Retry context that's updated between each retry attempt
+ * @returns Returns a Promise that resolves to `true` to continue retrying or `false` to stop retrying
+ *
+ * @example
+ * ```typescript
+ * const asyncHandler: AsyncRetryHandler = async (context) => {
+ *   // Retry up to 5 times
+ *   if (context.lastAttemptNumber >= 5) {
+ *     return false;
+ *   }
+ *   // Add exponential backoff
+ *   const delay = Math.min(1000 * Math.pow(2, context.lastAttemptNumber), 30000);
+ *   // Note: In practice you would use ctx.createTimer() for deterministic delays
+ *   return true;
+ * };
+ *
+ * const options = taskOptionsFromRetryHandler(asyncHandler);
+ * await ctx.callActivity("myActivity", input, options);
+ * ```
+ */
+export type AsyncRetryHandler = (retryContext: RetryContext) => Promise<boolean>;
+
+/**
+ * Creates an AsyncRetryHandler from a synchronous RetryHandler.
+ *
+ * @param handler - The synchronous retry handler to wrap
+ * @returns An AsyncRetryHandler that wraps the synchronous handler
+ *
+ * @example
+ * ```typescript
+ * const syncHandler: RetryHandler = (context) => context.lastAttemptNumber < 3;
+ * const asyncHandler = toAsyncRetryHandler(syncHandler);
+ * ```
+ */
+export function toAsyncRetryHandler(handler: RetryHandler): AsyncRetryHandler {
+  return (context: RetryContext) => Promise.resolve(handler(context));
+}