Versioning override

Author: Sushisource

packages/client/src/workflow-options.ts

@@ -1,7 +1,14 @@
-import { CommonWorkflowOptions, SignalDefinition, WithWorkflowArgs, Workflow } from '@temporalio/common';
+import {
+  CommonWorkflowOptions,
+  SignalDefinition,
+  WithWorkflowArgs,
+  Workflow,
+  VersioningOverride,
+  toCanonicalString,
+} from '@temporalio/common';
 import { Duration, msOptionalToTs } from '@temporalio/common/lib/time';
 import { Replace } from '@temporalio/common/lib/type-helpers';
-import { google } from '@temporalio/proto';
+import { google, temporal } from '@temporalio/proto';
 
 export * from '@temporalio/common/lib/workflow-options';
 
@@ -38,9 +45,15 @@ export interface WorkflowOptions extends CommonWorkflowOptions {
 
   /**
    * Amount of time to wait before starting the workflow.
-   *
    */
   startDelay?: Duration;
+
+  /**
+   * Override the versioning behavior of the Workflow that is about to be started.
+   *
+   * @experimental Deployment based versioning is experimental and may change in the future.
+   */
+  versioningOverride?: VersioningOverride;
 }
 
 export type WithCompiledWorkflowOptions<T extends WorkflowOptions> = Replace<
@@ -50,18 +63,21 @@ export type WithCompiledWorkflowOptions<T extends WorkflowOptions> = Replace<
     workflowRunTimeout?: google.protobuf.IDuration;
     workflowTaskTimeout?: google.protobuf.IDuration;
     startDelay?: google.protobuf.IDuration;
+    versioningOverride?: temporal.api.workflow.v1.IVersioningOverride;
   }
 >;
 
 export function compileWorkflowOptions<T extends WorkflowOptions>(options: T): WithCompiledWorkflowOptions<T> {
-  const { workflowExecutionTimeout, workflowRunTimeout, workflowTaskTimeout, startDelay, ...rest } = options;
+  const { workflowExecutionTimeout, workflowRunTimeout, workflowTaskTimeout, startDelay, versioningOverride, ...rest } =
+    options;
 
   return {
     ...rest,
     workflowExecutionTimeout: msOptionalToTs(workflowExecutionTimeout),
     workflowRunTimeout: msOptionalToTs(workflowRunTimeout),
     workflowTaskTimeout: msOptionalToTs(workflowTaskTimeout),
     startDelay: msOptionalToTs(startDelay),
+    versioningOverride: versioningOverrideToProto(versioningOverride),
   };
 }
 
@@ -109,3 +125,19 @@ export interface WorkflowSignalWithStartOptionsWithArgs<SignalArgs extends any[]
  * Options for starting a Workflow
  */
 export type WorkflowStartOptions<T extends Workflow = Workflow> = WithWorkflowArgs<T, WorkflowOptions>;
+
+function versioningOverrideToProto(
+  vo: VersioningOverride | undefined
+): temporal.api.workflow.v1.IVersioningOverride | undefined {
+  if (!vo) return undefined;
+  // TODO: Remove deprecated field assignments when versioning is non-experimental
+  if (vo === 'AUTO_UPGRADE') {
+    return {
+      behavior: temporal.api.enums.v1.VersioningBehavior.VERSIONING_BEHAVIOR_AUTO_UPGRADE,
+    };
+  }
+  return {
+    behavior: temporal.api.enums.v1.VersioningBehavior.VERSIONING_BEHAVIOR_PINNED,
+    pinnedVersion: toCanonicalString(vo.version),
+  };
+}

packages/common/src/worker-deployments.ts

@@ -22,8 +22,8 @@ export function toCanonicalString(version: WorkerDeploymentVersion): string {
 /**
  * Specifies when a workflow might move from a worker of one Build Id to another.
  *
- * * 'pinned' - The workflow will be pinned to the current Build ID unless manually moved.
- * * 'auto-upgrade' - The workflow will automatically move to the latest version (default Build ID
+ * * 'PINNED' - The workflow will be pinned to the current Build ID unless manually moved.
+ * * 'AUTO_UPGRADE' - The workflow will automatically move to the latest version (default Build ID
  *    of the task queue) when the next task is dispatched.
  *
  * @experimental Deployment based versioning is experimental and may change in the future.
@@ -48,3 +48,12 @@ export const [encodeVersioningBehavior, decodeVersioningBehavior] = makeProtoEnu
   } as const,
   'VERSIONING_BEHAVIOR_'
 );
+
+/**
+ * Represents versioning overrides. For example, when starting workflows.
+ *
+ * If set to 'AUTO_UPGRADE', the Workflow will run as if it is using {@link VersioningBehavior.AUTO_UPGRADE}.
+ * Otherwise, you select a pinned behavior, and a specific version to pin to. Currently only one
+ * such behavior exists, but more will be added in the future.
+ */
+export type VersioningOverride = { pinned_behavior: 'PINNED'; version: WorkerDeploymentVersion } | 'AUTO_UPGRADE';

packages/workflow/src/workflow.ts

@@ -24,7 +24,6 @@ import {
   SearchAttributeUpdatePair,
   compilePriority,
   WorkflowDefinitionOptionsOrGetter,
-  WorkflowFunctionWithOptions,
 } from '@temporalio/common';
 import {
   encodeUnifiedSearchAttributes,
@@ -1623,7 +1622,7 @@ export function allHandlersFinished(): boolean {
 export function setWorkflowOptions<A extends any[], RT>(
   options: WorkflowDefinitionOptionsOrGetter,
   fn: (...args: A) => Promise<RT>
-) {
+): void {
   Object.assign(fn, {
     workflowDefinitionOptions: options,
   });