Add Worker Deployment Versioning sample (#48)

Author: Sushisource

.gitignore

@@ -1,2 +1,3 @@
 .bundle
 .vscode
+.claude

test/worker_versioning/worker_versioning_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'test'
+require 'worker_versioning/app'
+require 'worker_versioning/workerv1'
+require 'worker_versioning/workerv1_1'
+require 'worker_versioning/workerv2'
+require 'temporalio/testing'
+
+module WorkerVersioning
+  class WorkerVersioningTest < Test
+    def test_worker_versioning_sample_can_run
+      skip_if_not_x86!
+
+      Temporalio::Testing::WorkflowEnvironment.start_local do |env|
+        worker_v1_task = Thread.new { WorkerVersioning::WorkerV1.run_async(env.client) }
+        worker_v1_1_task = Thread.new { WorkerVersioning::WorkerV1Dot1.run_async(env.client) }
+        worker_v2_task = Thread.new { WorkerVersioning::WorkerV2.run_async(env.client) }
+
+        begin
+          main(env.client)
+          assert(true, 'Worker versioning demo completed successfully')
+        ensure
+          [worker_v1_task, worker_v1_1_task, worker_v2_task].each(&:kill)
+        end
+      end
+    end
+  end
+end

worker_versioning/README.md

@@ -0,0 +1,26 @@
+## Worker Versioning
+
+This sample demonstrates how to use Temporal's Worker Versioning feature to safely deploy updates to workflow and activity code. It shows the difference between auto-upgrading and pinned workflows, and how to manage worker deployments with different build IDs.
+
+The sample creates multiple worker versions (1.0, 1.1, and 2.0) within one deployment and demonstrates:
+- **Auto-upgrading workflows**: Automatically and controllably migrate to newer worker versions
+- **Pinned workflows**: Stay on the original worker version throughout their lifecycle
+- **Compatible vs incompatible changes**: How to make safe updates using `Workflow.patched`
+
+### Steps to run this sample:
+
+1) Run a [Temporal service](https://github.com/temporalio/samples-ruby/tree/main/#how-to-use).
+   Ensure that you're using at least Server version 1.28.0 (CLI version 1.4.0).
+
+2) Start the main application (this will guide you through the sample):
+```bash
+ruby worker_versioning/app.rb
+```
+
+3) Follow the prompts to start workers in separate terminals:
+   - When prompted, run: `ruby worker_versioning/workerv1.rb`
+   - When prompted, run: `ruby worker_versioning/workerv1_1.rb`
+   - When prompted, run: `ruby worker_versioning/workerv2.rb`
+
+The sample will show how auto-upgrading workflows migrate to newer workers while pinned workflows
+remain on their original version.

worker_versioning/activities.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+
+module WorkerVersioning
+  module Activities
+    class SomeActivity < Temporalio::Activity::Definition
+      def execute(called_by)
+        "some_activity called by #{called_by}"
+      end
+    end
+
+    class SomeIncompatibleActivity < Temporalio::Activity::Definition
+      def execute(input_data)
+        "some_incompatible_activity called by #{input_data['called_by']} with #{input_data['more_data']}"
+      end
+    end
+  end
+end

worker_versioning/app.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+require 'temporalio/api/workflowservice/v1/request_response'
+require 'temporalio/worker_deployment_version'
+require 'logger'
+require 'securerandom'
+require_relative 'constants'
+
+def main(client = nil)
+  logger = Logger.new($stdout, level: Logger::INFO)
+
+  client ||= Temporalio::Client.connect(
+    'localhost:7233',
+    'default',
+    logger:
+  )
+
+  # Wait for v1 worker and set as current version
+  logger.info(
+    'Waiting for v1 worker to appear. Run `ruby worker_versioning/workerv1.rb` in another terminal'
+  )
+  wait_for_worker_and_make_current(client, '1.0')
+
+  # Start auto-upgrading and pinned workflows. Importantly, note that when we start the workflows,
+  # we are using a workflow type name which does *not* include the version number. We defined them
+  # with versioned names so we could show changes to the code, but here when the client invokes
+  # them, we're demonstrating that the client remains version-agnostic.
+  auto_upgrade_workflow_id = "worker-versioning-versioning-autoupgrade_#{SecureRandom.uuid}"
+  auto_upgrade_execution = client.start_workflow(
+    :AutoUpgrading,
+    id: auto_upgrade_workflow_id,
+    task_queue: WorkerVersioning::Constants::TASK_QUEUE
+  )
+
+  pinned_workflow_id = "worker-versioning-versioning-pinned_#{SecureRandom.uuid}"
+  pinned_execution = client.start_workflow(
+    :Pinned,
+    id: pinned_workflow_id,
+    task_queue: WorkerVersioning::Constants::TASK_QUEUE
+  )
+
+  logger.info("Started auto-upgrading workflow: #{auto_upgrade_execution.id}")
+  logger.info("Started pinned workflow: #{pinned_execution.id}")
+
+  # Signal both workflows a few times to drive them
+  advance_workflows(auto_upgrade_execution, pinned_execution)
+
+  # Now wait for the v1.1 worker to appear and become current
+  logger.info(
+    'Waiting for v1.1 worker to appear. Run `ruby worker_versioning/workerv1_1.rb` in another terminal'
+  )
+  wait_for_worker_and_make_current(client, '1.1')
+
+  # Once it has, we will continue to advance the workflows.
+  # The auto-upgrade workflow will now make progress on the new worker, while the pinned one will
+  # keep progressing on the old worker.
+  advance_workflows(auto_upgrade_execution, pinned_execution)
+
+  # Finally we'll start the v2 worker, and again it'll become the new current version
+  logger.info(
+    'Waiting for v2 worker to appear. Run `ruby worker_versioning/workerv2.rb` in another terminal'
+  )
+  wait_for_worker_and_make_current(client, '2.0')
+
+  # Once it has we'll start one more new workflow, another pinned one, to demonstrate that new
+  # pinned workflows start on the current version.
+  pinned_workflow_2_id = "worker-versioning-versioning-pinned-2_#{SecureRandom.uuid}"
+  pinned_execution_v2 = client.start_workflow(
+    :Pinned,
+    id: pinned_workflow_2_id,
+    task_queue: WorkerVersioning::Constants::TASK_QUEUE
+  )
+  logger.info("Started pinned workflow v2: #{pinned_execution_v2.id}")
+
+  # Now we'll conclude all workflows. You should be able to see in your server UI that the pinned
+  # workflow always stayed on 1.0, while the auto-upgrading workflow migrated.
+  [auto_upgrade_execution, pinned_execution, pinned_execution_v2].each do |handle|
+    handle.signal(:do_next_signal, 'conclude')
+    handle.result
+  end
+
+  logger.info('All workflows completed')
+end
+
+def advance_workflows(auto_upgrade_execution, pinned_execution)
+  # Signal both workflows a few times to drive them.
+  3.times do
+    auto_upgrade_execution.signal(:do_next_signal, 'do-activity')
+    pinned_execution.signal(:do_next_signal, 'some-signal')
+  end
+end
+
+def wait_for_worker_and_make_current(client, build_id)
+  target_version = Temporalio::WorkerDeploymentVersion.new(
+    deployment_name: WorkerVersioning::Constants::DEPLOYMENT_NAME,
+    build_id: build_id
+  )
+
+  loop do
+    describe_request = Temporalio::Api::WorkflowService::V1::DescribeWorkerDeploymentRequest.new(
+      namespace: client.namespace,
+      deployment_name: WorkerVersioning::Constants::DEPLOYMENT_NAME
+    )
+    response = client.workflow_service.describe_worker_deployment(describe_request)
+
+    found = response.worker_deployment_info.version_summaries.any? do |version_summary|
+      version_summary.deployment_version.deployment_name == target_version.deployment_name &&
+        version_summary.deployment_version.build_id == target_version.build_id
+    end
+
+    break if found
+
+    sleep(1)
+  rescue Temporalio::Error::RPCError => e
+    # If not-found, wait a second and try again
+    raise unless e.code == Temporalio::Error::RPCError::Code::NOT_FOUND
+
+    sleep(1)
+    next
+  end
+
+  # Once the version is available, set it as current
+  set_request = Temporalio::Api::WorkflowService::V1::SetWorkerDeploymentCurrentVersionRequest.new(
+    namespace: client.namespace,
+    deployment_name: WorkerVersioning::Constants::DEPLOYMENT_NAME,
+    version: target_version.to_canonical_string
+  )
+  client.workflow_service.set_worker_deployment_current_version(set_request)
+end
+
+main if __FILE__ == $PROGRAM_NAME

worker_versioning/constants.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module WorkerVersioning
+  module Constants
+    TASK_QUEUE = 'worker-versioning'
+    DEPLOYMENT_NAME = 'my-deployment'
+  end
+end

worker_versioning/workerv1.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'workflows'
+require_relative 'activities'
+require_relative 'constants'
+require 'logger'
+require 'temporalio/client'
+require 'temporalio/worker'
+require 'temporalio/worker/deployment_options'
+require 'temporalio/worker_deployment_version'
+
+module WorkerVersioning
+  module WorkerV1
+    def self.run_async(client)
+      worker = Temporalio::Worker.new(
+        client: client,
+        task_queue: WorkerVersioning::Constants::TASK_QUEUE,
+        workflows: [WorkerVersioning::Workflows::AutoUpgradingWorkflowV1,
+                    WorkerVersioning::Workflows::PinnedWorkflowV1],
+        activities: [WorkerVersioning::Activities::SomeActivity,
+                     WorkerVersioning::Activities::SomeIncompatibleActivity],
+        deployment_options: Temporalio::Worker::DeploymentOptions.new(
+          version: Temporalio::WorkerDeploymentVersion.new(
+            deployment_name: WorkerVersioning::Constants::DEPLOYMENT_NAME,
+            build_id: '1.0'
+          ),
+          use_worker_versioning: true
+        )
+      )
+      worker.run
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  logger = Logger.new($stdout, level: Logger::INFO)
+
+  client = Temporalio::Client.connect(
+    'localhost:7233',
+    'default',
+    logger: logger
+  )
+
+  logger.info('Starting worker v1 (build 1.0)')
+  WorkerVersioning::WorkerV1.run_async(client)
+end

worker_versioning/workerv1_1.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'workflows'
+require_relative 'activities'
+require_relative 'constants'
+require 'logger'
+require 'temporalio/client'
+require 'temporalio/worker'
+require 'temporalio/worker/deployment_options'
+require 'temporalio/worker_deployment_version'
+
+module WorkerVersioning
+  module WorkerV1Dot1
+    def self.run_async(client)
+      worker = Temporalio::Worker.new(
+        client: client,
+        task_queue: WorkerVersioning::Constants::TASK_QUEUE,
+        workflows: [WorkerVersioning::Workflows::AutoUpgradingWorkflowV1b,
+                    WorkerVersioning::Workflows::PinnedWorkflowV1],
+        activities: [WorkerVersioning::Activities::SomeActivity,
+                     WorkerVersioning::Activities::SomeIncompatibleActivity],
+        deployment_options: Temporalio::Worker::DeploymentOptions.new(
+          version: Temporalio::WorkerDeploymentVersion.new(
+            deployment_name: WorkerVersioning::Constants::DEPLOYMENT_NAME,
+            build_id: '1.1'
+          ),
+          use_worker_versioning: true
+        )
+      )
+      worker.run
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  logger = Logger.new($stdout, level: Logger::INFO)
+
+  client = Temporalio::Client.connect(
+    'localhost:7233',
+    'default',
+    logger: logger
+  )
+
+  logger.info('Starting worker v1.1 (build 1.1)')
+  WorkerVersioning::WorkerV1Dot1.run_async(client)
+end

worker_versioning/workerv2.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'workflows'
+require_relative 'activities'
+require_relative 'constants'
+require 'logger'
+require 'temporalio/client'
+require 'temporalio/worker'
+require 'temporalio/worker/deployment_options'
+require 'temporalio/worker_deployment_version'
+
+module WorkerVersioning
+  module WorkerV2
+    def self.run_async(client)
+      worker = Temporalio::Worker.new(
+        client: client,
+        task_queue: WorkerVersioning::Constants::TASK_QUEUE,
+        workflows: [WorkerVersioning::Workflows::AutoUpgradingWorkflowV1b,
+                    WorkerVersioning::Workflows::PinnedWorkflowV2],
+        activities: [WorkerVersioning::Activities::SomeActivity,
+                     WorkerVersioning::Activities::SomeIncompatibleActivity],
+        deployment_options: Temporalio::Worker::DeploymentOptions.new(
+          version: Temporalio::WorkerDeploymentVersion.new(
+            deployment_name: WorkerVersioning::Constants::DEPLOYMENT_NAME,
+            build_id: '2.0'
+          ),
+          use_worker_versioning: true
+        )
+      )
+      worker.run
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  logger = Logger.new($stdout, level: Logger::INFO)
+
+  client = Temporalio::Client.connect(
+    'localhost:7233',
+    'default',
+    logger: logger
+  )
+
+  logger.info('Starting worker v2 (build 2.0)')
+  WorkerVersioning::WorkerV2.run_async(client)
+end