Retry Handler Support when call activity or suborchestration

packages/durabletask-js/src/index.ts

@@ -62,18 +62,32 @@ 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,
+  RetryHandlerResult,
+  toAsyncRetryHandler,
+} from "./task/retry";
 export {
   TaskOptions,
   SubOrchestrationOptions,
   StartOrchestrationOptions,
-  taskOptionsFromRetryPolicy,
-  subOrchestrationOptionsFromRetryPolicy,
+  TaskRetryOptions,
+  isRetryPolicy,
+  isRetryHandler,
 } from "./task/options";
 
 // Types

packages/durabletask-js/src/task/exception/task-failed-error.ts

@@ -9,6 +9,7 @@ export class TaskFailedError extends Error {
 
   constructor(message: string, details: pb.TaskFailureDetails) {
     super(message);
+    this.name = "TaskFailedError";
 
     this._details = new FailureDetails(
       details.getErrormessage(),

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,7 @@ export {
   TaskOptions,
   SubOrchestrationOptions,
   StartOrchestrationOptions,
-  taskOptionsFromRetryPolicy,
-  subOrchestrationOptionsFromRetryPolicy,
+  TaskRetryOptions,
+  isRetryPolicy,
+  isRetryHandler,
 } from "./task-options";

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

@@ -2,16 +2,31 @@
 // Licensed under the MIT License.
 
 import { RetryPolicy } from "../retry/retry-policy";
+import { AsyncRetryHandler, RetryHandler } from "../retry/retry-handler";
+
+/**
+ * Union type representing the available retry strategies for a task.
+ *
+ * - {@link RetryPolicy} for declarative retry control (with backoff, max attempts, etc.)
+ * - {@link AsyncRetryHandler} for asynchronous imperative retry control
+ * - {@link RetryHandler} for synchronous imperative retry control
+ *
+ * When a synchronous {@link RetryHandler} is provided, it is automatically
+ * wrapped into an {@link AsyncRetryHandler} internally.
+ */
+export type TaskRetryOptions = RetryPolicy | AsyncRetryHandler | RetryHandler;
 
 /**
  * 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 a RetryPolicy for declarative retry control,
+   * an AsyncRetryHandler for async imperative retry control,
+   * or a RetryHandler for sync imperative retry control.
    */
-  retry?: RetryPolicy;
+  retry?: TaskRetryOptions;
   /**
    * The tags to associate with the task.
    */
@@ -62,45 +77,22 @@ export interface StartOrchestrationOptions {
 }
 
 /**
- * Creates a TaskOptions instance from a RetryPolicy.
+ * Type guard to check if the retry option is a RetryPolicy.
  *
- * @param policy - The retry policy to use
- * @returns A TaskOptions instance configured with the retry policy
- *
- * @example
- * ```typescript
- * const retryPolicy = new RetryPolicy({
- *   maxNumberOfAttempts: 3,
- *   firstRetryIntervalInMilliseconds: 1000
- * });
- *
- * const options = taskOptionsFromRetryPolicy(retryPolicy);
- * ```
+ * @param retry - The retry option to check
+ * @returns true if the retry option is a RetryPolicy, false otherwise
  */
-export function taskOptionsFromRetryPolicy(policy: RetryPolicy): TaskOptions {
-  return { retry: policy };
+export function isRetryPolicy(retry: TaskRetryOptions | undefined): retry is RetryPolicy {
+  return retry instanceof RetryPolicy;
 }
 
 /**
- * Creates a SubOrchestrationOptions instance from a RetryPolicy and optional instance ID.
- *
- * @param policy - The retry policy to use
- * @param instanceId - Optional instance ID for the sub-orchestration
- * @returns A SubOrchestrationOptions instance configured with the retry policy
- *
- * @example
- * ```typescript
- * const retryPolicy = new RetryPolicy({
- *   maxNumberOfAttempts: 3,
- *   firstRetryIntervalInMilliseconds: 1000
- * });
+ * Type guard to check if the retry option is a retry handler function
+ * (either {@link AsyncRetryHandler} or {@link RetryHandler}).
  *
- * const options = subOrchestrationOptionsFromRetryPolicy(retryPolicy, "my-sub-orch-123");
- * ```
+ * @param retry - The retry option to check
+ * @returns true if the retry option is a handler function, false otherwise
  */
-export function subOrchestrationOptionsFromRetryPolicy(
-  policy: RetryPolicy,
-  instanceId?: string,
-): SubOrchestrationOptions {
-  return { retry: policy, instanceId };
+export function isRetryHandler(retry: TaskRetryOptions | undefined): retry is AsyncRetryHandler | RetryHandler {
+  return typeof retry === "function";
 }

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

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as pb from "../proto/orchestrator_service_pb";
+import { OrchestrationContext } from "./context/orchestration-context";
+import { RetryTaskBase, RetryTaskType } from "./retry-task-base";
+import { AsyncRetryHandler, RetryHandlerResult } from "./retry/retry-handler";
+import { createRetryContext } from "./retry/retry-context";
+import { TaskFailureDetails } from "./failure-details";
+
+/**
+ * A task that uses an AsyncRetryHandler for imperative retry control.
+ *
+ * @remarks
+ * Unlike RetryableTask which uses a declarative RetryPolicy, this task delegates
+ * all retry decisions to a user-provided handler function. The handler receives
+ * a RetryContext with failure details, attempt count, and elapsed time, and
+ * returns true to retry or false to stop.
+ *
+ * This mirrors the .NET SDK's InvokeWithCustomRetryHandler pattern, where the
+ * retry handler runs as orchestrator code (subject to replay).
+ */
+export class RetryHandlerTask<T> extends RetryTaskBase<T> {
+  private readonly _handler: AsyncRetryHandler;
+  private readonly _orchestrationContext: OrchestrationContext;
+
+  /**
+   * Creates a new RetryHandlerTask instance.
+   *
+   * @param handler - The async retry handler for imperative retry decisions
+   * @param orchestrationContext - The orchestration context for the current execution
+   * @param action - The orchestrator action associated with this task
+   * @param startTime - The time when the task was first scheduled
+   * @param taskType - The type of task (activity or sub-orchestration)
+   */
+  constructor(
+    handler: AsyncRetryHandler,
+    orchestrationContext: OrchestrationContext,
+    action: pb.OrchestratorAction,
+    startTime: Date,
+    taskType: RetryTaskType,
+  ) {
+    super(action, startTime, taskType);
+    if (!handler) {  
+        throw new Error("RetryHandlerTask requires a non-null handler");  
+    }
+    this._handler = handler;
+    this._orchestrationContext = orchestrationContext;
+  }
+
+  /**
+   * Gets the async retry handler for this task.
+   */
+  get handler(): AsyncRetryHandler {
+    return this._handler;
+  }
+
+  /**
+   * Invokes the async retry handler to determine whether to retry.
+   *
+   * @param currentTime - The current orchestration time (for deterministic replay)
+   * @returns A Promise that resolves to `true` to retry immediately,
+   *   `false` to stop retrying, or a positive number indicating the
+   *   delay in milliseconds before the next retry attempt
+   */
+  async shouldRetry(currentTime: Date): Promise<RetryHandlerResult> {
+    if (!this.lastFailure) {
+      return false;
+    }
+
+    // Check for non-retriable failures (e.g., activity not found)
+    if (this.lastFailure.getIsnonretriable()) {
+      return false;
+    }
+
+    const failureDetails: TaskFailureDetails = {
+      errorType: this.lastFailure.getErrortype() || "Error",
+      message: this.lastFailure.getErrormessage() || "",
+      stackTrace: this.lastFailure.getStacktrace()?.getValue(),
+    };
+
+    const totalRetryTimeMs = currentTime.getTime() - this.startTime.getTime();
+
+    const retryContext = createRetryContext(
+      this._orchestrationContext,
+      this.attemptCount,
+      failureDetails,
+      totalRetryTimeMs,
+    );
+
+    return this._handler(retryContext);
+  }
+}