feat: Implement versioning support with default version handling and version comparison methods

Author: YunchuWang

packages/durabletask-js/src/client/client.ts

@@ -49,12 +49,19 @@ export interface TaskHubGrpcClientOptions {
   metadataGenerator?: MetadataGenerator;
   /** Optional logger instance. Defaults to ConsoleLogger. */
   logger?: Logger;
+  /**
+   * The default version to use when starting new orchestrations without an explicit version.
+   * If specified, this will be used as the version for orchestrations that don't provide
+   * their own version in StartOrchestrationOptions.
+   */
+  defaultVersion?: string;
 }
 
 export class TaskHubGrpcClient {
   private _stub: stubs.TaskHubSidecarServiceClient;
   private _metadataGenerator?: MetadataGenerator;
   private _logger: Logger;
+  private _defaultVersion?: string;
 
   /**
    * Creates a new TaskHubGrpcClient instance.
@@ -97,6 +104,7 @@ export class TaskHubGrpcClient {
     let resolvedCredentials: grpc.ChannelCredentials | undefined;
     let resolvedMetadataGenerator: MetadataGenerator | undefined;
     let resolvedLogger: Logger | undefined;
+    let resolvedDefaultVersion: string | undefined;
 
     if (typeof hostAddressOrOptions === "object" && hostAddressOrOptions !== null) {
       // Options object constructor
@@ -106,6 +114,7 @@ export class TaskHubGrpcClient {
       resolvedCredentials = hostAddressOrOptions.credentials;
       resolvedMetadataGenerator = hostAddressOrOptions.metadataGenerator;
       resolvedLogger = hostAddressOrOptions.logger;
+      resolvedDefaultVersion = hostAddressOrOptions.defaultVersion;
     } else {
       // Deprecated positional parameters constructor
       resolvedHostAddress = hostAddressOrOptions;
@@ -119,6 +128,7 @@ export class TaskHubGrpcClient {
     this._stub = new GrpcClient(resolvedHostAddress, resolvedOptions, resolvedUseTLS, resolvedCredentials).stub;
     this._metadataGenerator = resolvedMetadataGenerator;
     this._logger = resolvedLogger ?? new ConsoleLogger();
+    this._defaultVersion = resolvedDefaultVersion;
   }
 
   async stop(): Promise<void> {
@@ -184,6 +194,9 @@ export class TaskHubGrpcClient {
         ? undefined
         : instanceIdOrOptions.version;
 
+    // Use provided version, or fall back to client's default version
+    const effectiveVersion = version ?? this._defaultVersion;
+
     const req = new pb.CreateInstanceRequest();
     req.setName(name);
     req.setInstanceid(instanceId ?? randomUUID());
@@ -197,15 +210,15 @@ export class TaskHubGrpcClient {
     req.setInput(i);
     req.setScheduledstarttimestamp(ts);
 
-    if (version) {
+    if (effectiveVersion) {
       const v = new StringValue();
-      v.setValue(version);
+      v.setValue(effectiveVersion);
       req.setVersion(v);
     }
 
     populateTagsMap(req.getTagsMap(), tags);
 
-    this._logger.info(`Starting new ${name} instance with ID = ${req.getInstanceid()}${version ? ` (version: ${version})` : ''}`);
+    this._logger.info(`Starting new ${name} instance with ID = ${req.getInstanceid()}${effectiveVersion ? ` (version: ${effectiveVersion})` : ''}`);
 
     const res = await callWithMetadata<pb.CreateInstanceRequest, pb.CreateInstanceResponse>(
       this._stub.startInstance.bind(this._stub),

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

@@ -7,6 +7,7 @@ import { Logger } from "../../types/logger.type";
 import { ReplaySafeLogger } from "../../types/replay-safe-logger";
 import { TaskOptions, SubOrchestrationOptions } from "../options";
 import { Task } from "../task";
+import { compareVersions } from "../../utils/versioning.util";
 
 export abstract class OrchestrationContext {
   /**
@@ -51,6 +52,35 @@ export abstract class OrchestrationContext {
    */
   abstract get version(): string;
 
+  /**
+   * Compares the current orchestration version to the specified version.
+   *
+   * This method uses semantic versioning comparison when both versions are valid
+   * semantic versions, and falls back to lexicographic comparison otherwise.
+   *
+   * @remarks
+   * - If both versions are empty, this returns 0 (equal).
+   * - An empty context version is considered less than a defined version.
+   * - An empty parameter version is considered less than a defined context version.
+   *
+   * @param {string} version The version to compare against.
+   * @returns {number} A negative number if context version < parameter version,
+   *                   zero if equal, positive if context version > parameter version.
+   *
+   * @example
+   * ```typescript
+   * const orchestrator: TOrchestrator = async function* (ctx, input) {
+   *   if (ctx.compareVersionTo("2.0.0") >= 0) {
+   *     // This orchestration is version 2.0.0 or newer
+   *     yield ctx.callActivity(newFeature, input);
+   *   }
+   * };
+   * ```
+   */
+  compareVersionTo(version: string): number {
+    return compareVersions(this.version, version);
+  }
+
   /**
    * Create a timer task that will fire at a specified time.
    *

packages/durabletask-js/src/utils/pb-helper.util.ts

@@ -181,6 +181,22 @@ export function newFailureDetails(e: any): pb.TaskFailureDetails {
   return failure;
 }
 
+/**
+ * Creates a TaskFailureDetails for version mismatch errors.
+ * These errors are non-retriable as the version mismatch is deterministic.
+ *
+ * @param errorType The type of version error (e.g., "VersionMismatch", "VersionError")
+ * @param errorMessage The error message describing the version mismatch
+ * @returns A TaskFailureDetails with IsNonRetriable set to true
+ */
+export function newVersionMismatchFailureDetails(errorType: string, errorMessage: string): pb.TaskFailureDetails {
+  const failure = new pb.TaskFailureDetails();
+  failure.setErrortype(errorType);
+  failure.setErrormessage(errorMessage);
+  failure.setIsnonretriable(true);
+  return failure;
+}
+
 export function newEventRaisedEvent(name: string, encodedInput?: string): pb.HistoryEvent {
   const ts = new Timestamp();
 

packages/durabletask-js/src/worker/task-hub-grpc-worker.ts

@@ -415,6 +415,8 @@ export class TaskHubGrpcWorker {
     compatible: boolean;
     shouldFail: boolean;
     orchestrationVersion?: string;
+    errorType?: string;
+    errorMessage?: string;
   } {
     // If no versioning options configured or match strategy is None, always compatible
     if (!this._versioning || this._versioning.matchStrategy === VersionMatchStrategy.None) {
@@ -431,11 +433,16 @@ export class TaskHubGrpcWorker {
     }
 
     let compatible = false;
+    let errorType = "VersionMismatch";
+    let errorMessage = "";
 
     switch (this._versioning.matchStrategy) {
       case VersionMatchStrategy.Strict:
-        // Only process if versions match exactly
-        compatible = orchestrationVersion === workerVersion;
+        // Only process if versions match (using semantic comparison)
+        compatible = compareVersions(orchestrationVersion, workerVersion) === 0;
+        if (!compatible) {
+          errorMessage = `The orchestration version '${orchestrationVersion ?? ""}' does not match the worker version '${workerVersion}'.`;
+        }
         break;
 
       case VersionMatchStrategy.CurrentOrOlder:
@@ -445,16 +452,23 @@ export class TaskHubGrpcWorker {
           compatible = true;
         } else {
           compatible = compareVersions(orchestrationVersion, workerVersion) <= 0;
+          if (!compatible) {
+            errorMessage = `The orchestration version '${orchestrationVersion}' is greater than the worker version '${workerVersion}'.`;
+          }
         }
         break;
 
       default:
-        compatible = true;
+        // Unknown match strategy - treat as version error
+        compatible = false;
+        errorType = "VersionError";
+        errorMessage = `The version match strategy '${this._versioning.matchStrategy}' is unknown.`;
+        break;
     }
 
     if (!compatible) {
       const shouldFail = this._versioning.failureStrategy === VersionFailureStrategy.Fail;
-      return { compatible: false, shouldFail, orchestrationVersion };
+      return { compatible: false, shouldFail, orchestrationVersion, errorType, errorMessage };
     }
 
     return { compatible: true, shouldFail: false };
@@ -511,18 +525,20 @@ export class TaskHubGrpcWorker {
       if (versionCheckResult.shouldFail) {
         // Fail the orchestration with version mismatch error
         this._logger.warn(
-          `Version mismatch for instance '${instanceId}': orchestration version '${versionCheckResult.orchestrationVersion}' does not match worker version '${this._versioning?.version}'. Failing orchestration.`,
+          `${versionCheckResult.errorType} for instance '${instanceId}': ${versionCheckResult.errorMessage}. Failing orchestration.`,
         );
 
-        const failureDetails = pbh.newFailureDetails(
-          new Error(`Version mismatch: orchestration version '${versionCheckResult.orchestrationVersion}' is not compatible with worker version '${this._versioning?.version}'`),
+        const failureDetails = pbh.newVersionMismatchFailureDetails(
+          versionCheckResult.errorType!,
+          versionCheckResult.errorMessage!,
         );
 
         const actions = [
           pbh.newCompleteOrchestrationAction(
             -1,
             pb.OrchestrationStatus.ORCHESTRATION_STATUS_FAILED,
-            failureDetails?.toString(),
+            undefined,
+            failureDetails,
           ),
         ];
 
@@ -540,7 +556,7 @@ export class TaskHubGrpcWorker {
       } else {
         // Reject the work item - explicitly abandon it so it can be picked up by another worker
         this._logger.info(
-          `Version mismatch for instance '${instanceId}': orchestration version '${versionCheckResult.orchestrationVersion}' does not match worker version '${this._versioning?.version}'. Abandoning work item.`,
+          `${versionCheckResult.errorType} for instance '${instanceId}': ${versionCheckResult.errorMessage}. Abandoning work item.`,
         );
 
         try {

packages/durabletask-js/src/worker/versioning-options.ts

@@ -48,6 +48,12 @@ export interface VersioningOptions {
    */
   version?: string;
 
+  /**
+   * The default version to use when starting new orchestrations without an explicit version.
+   * This is used by the client when scheduling new orchestrations.
+   */
+  defaultVersion?: string;
+
   /**
    * The strategy for matching orchestration versions.
    * @default VersionMatchStrategy.None

packages/durabletask-js/test/client-options.spec.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { TaskHubGrpcClient, TaskHubGrpcClientOptions } from "../src";
+
+describe("TaskHubGrpcClient", () => {
+  describe("constructor with options", () => {
+    it("should accept default version option", () => {
+      const options: TaskHubGrpcClientOptions = {
+        hostAddress: "localhost:4001",
+        defaultVersion: "1.0.0",
+      };
+
+      // This should not throw
+      const client = new TaskHubGrpcClient(options);
+
+      expect(client).toBeDefined();
+    });
+
+    it("should work without default version option", () => {
+      const options: TaskHubGrpcClientOptions = {
+        hostAddress: "localhost:4001",
+      };
+
+      const client = new TaskHubGrpcClient(options);
+
+      expect(client).toBeDefined();
+    });
+
+    it("should accept all standard options", () => {
+      const options: TaskHubGrpcClientOptions = {
+        hostAddress: "localhost:4001",
+        useTLS: false,
+        defaultVersion: "2.0.0",
+      };
+
+      const client = new TaskHubGrpcClient(options);
+
+      expect(client).toBeDefined();
+    });
+  });
+});