Add versioning override

Sushisource · Sushisource · commit b3604f9e073f · 2025-05-14T10:54:22.000-07:00
diff --git a/temporalio/lib/temporalio.rb b/temporalio/lib/temporalio.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'temporalio/version'
+require 'temporalio/versioning_override'
 
 # Temporal Ruby SDK. See the README at https://github.com/temporalio/sdk-ruby.
 module Temporalio
diff --git a/temporalio/lib/temporalio/client.rb b/temporalio/lib/temporalio/client.rb
@@ -22,6 +22,7 @@
 require 'temporalio/retry_policy'
 require 'temporalio/runtime'
 require 'temporalio/search_attributes'
+require 'temporalio/versioning_override'
 require 'temporalio/workflow/definition'
 
 module Temporalio
@@ -239,6 +240,7 @@ def start_workflow(
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
+      versioning_override: nil,
       rpc_options: nil
     )
       @impl.start_workflow(Interceptor::StartWorkflowInput.new(
@@ -260,6 +262,7 @@ def start_workflow(
                              start_delay:,
                              request_eager_start:,
                              headers: {},
+                             versioning_override:,
                              rpc_options:
                            ))
     end
@@ -316,9 +319,11 @@ def execute_workflow(
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
+      versioning_override: nil,
+      follow_runs: true,
       rpc_options: nil
     )
-      start_workflow(
+      handle = start_workflow(
         workflow,
         *args,
         id:,
@@ -336,8 +341,10 @@ def execute_workflow(
         search_attributes:,
         start_delay:,
         request_eager_start:,
+        versioning_override:,
         rpc_options:
-      ).result
+      )
+      follow_runs ? handle.result : handle
     end
 
     # Get a workflow handle to an existing workflow by its ID.
diff --git a/temporalio/lib/temporalio/client/interceptor.rb b/temporalio/lib/temporalio/client/interceptor.rb
@@ -37,6 +37,7 @@ def intercept_client(next_interceptor)
         :start_delay,
         :request_eager_start,
         :headers,
+        :versioning_override,
         :rpc_options
       )
 
diff --git a/temporalio/lib/temporalio/internal/client/implementation.rb b/temporalio/lib/temporalio/internal/client/implementation.rb
@@ -69,7 +69,8 @@ def start_workflow(input)
             user_metadata: ProtoUtils.to_user_metadata(
               input.static_summary, input.static_details, @client.data_converter
             ),
-            header: ProtoUtils.headers_to_proto(input.headers, @client.data_converter)
+            header: ProtoUtils.headers_to_proto(input.headers, @client.data_converter),
+            versioning_override: input.versioning_override&._to_proto
           )
 
           # Send request
diff --git a/temporalio/lib/temporalio/internal/worker/workflow_instance.rb b/temporalio/lib/temporalio/internal/worker/workflow_instance.rb
@@ -57,7 +57,7 @@ def self.new_completion_with_failure(run_id:, error:, failure_converter:, payloa
                     :pending_external_signals, :pending_external_cancels, :in_progress_handlers, :payload_converter,
                     :failure_converter, :cancellation, :continue_as_new_suggested, :current_deployment_version,
                     :current_history_length, :current_history_size, :replaying, :random,
-                    :signal_handlers, :query_handlers, :update_handlers, :context_frozen, :assert_valid_local_history
+                    :signal_handlers, :query_handlers, :update_handlers, :context_frozen, :assert_valid_local_activity
         attr_accessor :io_enabled, :current_details
 
         def initialize(details)
diff --git a/temporalio/lib/temporalio/versioning_override.rb b/temporalio/lib/temporalio/versioning_override.rb
@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'temporalio/worker_deployment_version'
+
+module Temporalio
+  # Base class for version overrides that can be provided in start workflow options.
+  # Used to control the versioning behavior of workflows started with this override.
+  #
+  # Use factory methods {.auto_upgrade} or {.pinned} to create instances.
+  #
+  # WARNING: Experimental API.
+  class VersioningOverride
+    # Creates an auto-upgrade versioning override
+    # The workflow will auto-upgrade to the current deployment version on the next workflow task.
+    #
+    # @return [AutoUpgradeVersioningOverride] An auto-upgrade versioning override
+    def self.auto_upgrade
+      AutoUpgradeVersioningOverride.new
+    end
+
+    # Creates a pinned versioning override
+    # The workflow will be pinned to a specific deployment version.
+    #
+    # @param version [WorkerDeploymentVersion] The worker deployment version to pin the workflow to
+    # @return [PinnedVersioningOverride] A pinned versioning override
+    def self.pinned(version)
+      PinnedVersioningOverride.new(version)
+    end
+
+    # @!visibility private
+    def _to_proto
+      raise NotImplementedError, 'Subclasses must implement this method'
+    end
+  end
+
+  # Represents a versioning override to pin a workflow to a specific version
+  class PinnedVersioningOverride < VersioningOverride
+    # The worker deployment version to pin to
+    # @return [WorkerDeploymentVersion]
+    attr_reader :version
+
+    # Create a new pinned versioning override
+    #
+    # @param version [WorkerDeploymentVersion] The worker deployment version to pin to
+    def initialize(version)
+      @version = version
+      super()
+    end
+
+    # TODO: Remove deprecated field setting once removed from server
+
+    # @!visibility private
+    def _to_proto
+      Temporalio::Api::Workflow::V1::VersioningOverride.new(
+        behavior: Temporalio::Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_PINNED,
+        pinned_version: @version.to_canonical_string,
+        pinned: Temporalio::Api::Workflow::V1::VersioningOverride::PinnedOverride.new(
+          version: @version._to_proto
+        )
+      )
+    end
+  end
+
+  # Represents a versioning override to auto-upgrade a workflow
+  class AutoUpgradeVersioningOverride < VersioningOverride
+    # @!visibility private
+    def _to_proto
+      Temporalio::Api::Workflow::V1::VersioningOverride.new(
+        behavior: Temporalio::Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_AUTO_UPGRADE,
+        auto_upgrade: true
+      )
+    end
+  end
+end
diff --git a/temporalio/lib/temporalio/worker/workflow_replayer.rb b/temporalio/lib/temporalio/worker/workflow_replayer.rb
@@ -217,7 +217,10 @@ def initialize(
               graceful_shutdown_period: 0.0,
               nondeterminism_as_workflow_fail:,
               nondeterminism_as_workflow_fail_for_types:,
-              deployment_options: nil
+              deployment_options: DeploymentOptions.new(
+                version: WorkerDeploymentVersion.new(deployment_name: '',
+                                                     build_id: Worker.default_build_id)
+              )._to_bridge_options
             )
           )
 
diff --git a/temporalio/lib/temporalio/worker_deployment_version.rb b/temporalio/lib/temporalio/worker_deployment_version.rb
@@ -55,5 +55,13 @@ def _to_bridge_options
         build_id: build_id
       )
     end
+
+    # @!visibility private
+    def _to_proto
+      Api::Deployment::V1::WorkerDeploymentVersion.new(
+        deployment_name: deployment_name,
+        build_id: build_id
+      )
+    end
   end
 end
diff --git a/temporalio/lib/temporalio/workflow/definition.rb b/temporalio/lib/temporalio/workflow/definition.rb
@@ -643,7 +643,7 @@ def _with_validator_to_invoke(validator_to_invoke)
       :versioning_behavior
     )
     # @!attribute failure_exception_types
-    #   Dynamic equivalent of {Definition.Info.workflow_failure_exception_types}.
+    #   Dynamic equivalent of {Definition.workflow_failure_exception_type}.
     #   Will override any types set there if set, including if set to an empty array.
     #   @return [Array<Class<Exception>>, nil] The failure exception types
     #
diff --git a/temporalio/sig/temporalio/client.rbs b/temporalio/sig/temporalio/client.rbs
@@ -75,6 +75,7 @@ module Temporalio
       ?search_attributes: SearchAttributes?,
       ?start_delay: duration?,
       ?request_eager_start: bool,
+      ?versioning_override: VersioningOverride?,
       ?rpc_options: RPCOptions?
     ) -> WorkflowHandle
 
@@ -96,6 +97,8 @@ module Temporalio
       ?search_attributes: SearchAttributes?,
       ?start_delay: duration?,
       ?request_eager_start: bool,
+      ?versioning_override: VersioningOverride?,
+      ?follow_runs: bool,
       ?rpc_options: RPCOptions?
     ) -> Object?
 
diff --git a/temporalio/sig/temporalio/client/interceptor.rbs b/temporalio/sig/temporalio/client/interceptor.rbs
@@ -22,6 +22,7 @@ module Temporalio
         attr_reader start_delay: duration?
         attr_reader request_eager_start: bool
         attr_reader headers: Hash[String, Object?]
+        attr_reader versioning_override: VersioningOverride?
         attr_reader rpc_options: RPCOptions?
 
         def initialize: (
@@ -43,6 +44,7 @@ module Temporalio
           start_delay: duration?,
           request_eager_start: bool,
           headers: Hash[String, Object?],
+          versioning_override: VersioningOverride?,
           rpc_options: RPCOptions?
         ) -> void
       end
diff --git a/temporalio/sig/temporalio/versioning_override.rbs b/temporalio/sig/temporalio/versioning_override.rbs
@@ -0,0 +1,20 @@
+module Temporalio
+  class VersioningOverride
+    def self.auto_upgrade: -> AutoUpgradeVersioningOverride
+    def self.pinned: (WorkerDeploymentVersion version) -> PinnedVersioningOverride
+
+    def _to_proto: -> untyped
+  end
+
+  class PinnedVersioningOverride < VersioningOverride
+    attr_reader version: WorkerDeploymentVersion
+
+    def initialize: (WorkerDeploymentVersion version) -> void
+    def _to_proto: -> untyped
+  end
+
+  class AutoUpgradeVersioningOverride < VersioningOverride
+    def initialize: -> void
+    def _to_proto: -> untyped
+  end
+end
diff --git a/temporalio/sig/temporalio/worker_deployment_version.rbs b/temporalio/sig/temporalio/worker_deployment_version.rbs
@@ -12,5 +12,6 @@ module Temporalio
     def to_canonical_string: -> String
 
     def _to_bridge_options: -> Internal::Bridge::Worker::WorkerDeploymentVersion
+    def _to_proto: -> untyped
   end
 end
diff --git a/temporalio/test/worker_workflow_test.rb b/temporalio/test/worker_workflow_test.rb
@@ -2317,6 +2317,7 @@ def test_no_local_activity
       assert_eventually_task_fail(handle:, message_contains:)
     end
   end
+end
 
 # TODO(cretz): To test
 # * Common
diff --git a/temporalio/test/worker_workflow_versioning_test.rb b/temporalio/test/worker_workflow_versioning_test.rb
@@ -520,4 +520,51 @@ def set_ramping_version(client, conflict_token, version, percentage)
       )
     )
   end
+
+  def test_workflows_can_use_versioning_override
+    # Test that versioning override works when starting a workflow
+    deployment_name = "deployment-versioning-override-#{SecureRandom.uuid}"
+    worker_v1 = Temporalio::WorkerDeploymentVersion.new(
+      deployment_name: deployment_name,
+      build_id: '1.0'
+    )
+    task_queue = "tq-#{SecureRandom.uuid}"
+
+    require 'temporalio/versioning_override'
+
+    worker = Temporalio::Worker.new(
+      client: env.client,
+      task_queue: task_queue,
+      workflows: [DeploymentVersioningWorkflowV1AutoUpgrade],
+      deployment_options: Temporalio::Worker::DeploymentOptions.new(
+        version: worker_v1, use_worker_versioning: true
+      )
+    )
+
+    worker.run do
+      # Wait for deployment to be visible
+      describe_resp = wait_until_worker_deployment_visible(env.client, worker_v1)
+      # Set current deployment version
+      set_current_deployment_version(env.client, describe_resp.conflict_token, worker_v1)
+
+      # Start workflow with pinned versioning override
+      handle = env.client.start_workflow(
+        DeploymentVersioningWorkflowV1AutoUpgrade,
+        id: "override-versioning-#{SecureRandom.uuid}",
+        task_queue: task_queue,
+        versioning_override: Temporalio::VersioningOverride.pinned(worker_v1)
+      )
+
+      # Send signal to finish
+      handle.signal(:do_finish)
+      # Wait for workflow to complete
+      handle.result
+
+      # Verify in the history that versioning override was applied
+      history = handle.fetch_history
+      execution_started_event = history.events.find { |evt| evt.event_type == :EVENT_TYPE_WORKFLOW_EXECUTION_STARTED }
+      # Check if the versioning override is present in the workflow execution started event
+      assert(execution_started_event.workflow_execution_started_event_attributes.versioning_override)
+    end
+  end
 end

Original file line number	Diff line number	Diff line change
`@@ -37,6 +37,7 @@ def intercept_client(next_interceptor)`
`37`	`37`	`:start_delay,`
`38`	`38`	`:request_eager_start,`
`39`	`39`	`:headers,`
	`40`	`+ :versioning_override,`
`40`	`41`	`:rpc_options`
`41`	`42`	`)`
`42`	`43`
Original file line number	Diff line number	Diff line change
`@@ -69,7 +69,8 @@ def start_workflow(input)`
`69`	`69`	`user_metadata: ProtoUtils.to_user_metadata(`
`70`	`70`	`input.static_summary, input.static_details, @client.data_converter`
`71`	`71`	`),`
`72`		`- header: ProtoUtils.headers_to_proto(input.headers, @client.data_converter)`
	`72`	`+ header: ProtoUtils.headers_to_proto(input.headers, @client.data_converter),`
	`73`	`+ versioning_override: input.versioning_override&._to_proto`
`73`	`74`	`)`
`74`	`75`
`75`	`76`	`# Send request`
Original file line number	Diff line number	Diff line change
`@@ -217,7 +217,10 @@ def initialize(`
`217`	`217`	`graceful_shutdown_period: 0.0,`
`218`	`218`	`nondeterminism_as_workflow_fail:,`
`219`	`219`	`nondeterminism_as_workflow_fail_for_types:,`
`220`		`- deployment_options: nil`
	`220`	`+ deployment_options: DeploymentOptions.new(`
	`221`	`+ version: WorkerDeploymentVersion.new(deployment_name: '',`
	`222`	`+ build_id: Worker.default_build_id)`
	`223`	`+ )._to_bridge_options`
`221`	`224`	`)`
`222`	`225`	`)`
`223`	`226`
Original file line number	Diff line number	Diff line change
`@@ -643,7 +643,7 @@ def _with_validator_to_invoke(validator_to_invoke)`
`643`	`643`	`:versioning_behavior`
`644`	`644`	`)`
`645`	`645`	`# @!attribute failure_exception_types`
`646`		`- # Dynamic equivalent of {Definition.Info.workflow_failure_exception_types}.`
	`646`	`+ # Dynamic equivalent of {Definition.workflow_failure_exception_type}.`
`647`	`647`	`# Will override any types set there if set, including if set to an empty array.`
`648`	`648`	`# @return [Array<Class<Exception>>, nil] The failure exception types`
`649`	`649`	`#`