add patching sample (#56)

* add patching sample

* add comments

* pr feedback

Author: chris-olszewski

README.md

@@ -27,6 +27,7 @@ Prerequisites:
 * [encryption](encryption) - Demonstrates how to make a codec for end-to-end encryption.
 * [env_config](env_config) - Load client configuration from TOML files with programmatic overrides.
 * [message_passing_simple](message_passing_simple) - Simple workflow that accepts signals, queries, and updates.
+* [patching](patching) - Demonstrates how to safely alter a workflow.
 * [polling/infrequent](polling/infrequent) - Implement an infrequent polling mechanism using Temporal's automatic Activity Retry feature.
 * [rails_app](rails_app) - Basic Rails API application using Temporal workflows and activities.
 * [saga](saga) - Using undo/compensation using a very simplistic Saga pattern.
@@ -40,4 +41,3 @@ Prerequisites:
 To check format and test this repository, run:
 
     bundle exec rake
-

patching/README.md

@@ -0,0 +1,141 @@
+# Patching
+
+This sample shows how to safely update a workflow in stages using `Temporalio::Workflow.patch` and `Temporalio::Workflow.deprecate_patch`.
+
+To run, first see [README.md](../README.md) for prerequisites. Then follow the stages below.
+
+## Stage 1
+
+To simulate our initial workflow, start a worker in another terminal
+
+```bash
+  bundle exec ruby worker.rb initial
+```
+
+Now start a workflow:
+
+```bash
+  bundle exec ruby starter.rb start initial-id
+```
+
+This will output `Started workflow with id initial-id`.
+
+Now query the workflow:
+
+```bash
+  bundle exec ruby starter.rb query initial-id
+```
+
+This will output `Query result for id initial-id: pre-patch`
+
+## Stage 2
+
+This stage is for needing to run old and new workflows at the same time.
+To simulate our patched workflow, stop the worker from before and start it again with the patched workflow:
+
+```bash
+  bundle exec ruby worker.rb patched
+```
+
+Now let's start another workflow with this patched code:
+
+```bash
+  bundle exec ruby starter.rb start patched-id
+```
+
+This will output `Started workflow with id patched-id-workflow-id`.
+
+Now query the old workflow that's still running:
+
+```bash
+  bundle exec starter.rb query initial-id
+```
+
+This will output "Query result for id initial-id: pre-patch" since it is pre-patch.
+
+But if we execute a query against the new code:
+
+```bash
+  bundle exec starter.rb query patched-id
+```
+
+We get "Query result for id patched-id: post-patch".
+
+This is how old workflow code can take old paths and new workflow code can take new paths.
+
+## Stage 3
+
+Once we know that all workflows that started with the initial code from "Stage 1" are no longer running,
+we don't need the patch so we can deprecate it.
+To use the patch deprecated workflow, stop the worker from before and start it again with:
+
+```bash
+  bundle exec ruby worker.rb deprecated
+```
+
+Querying the initial workflow should error now.
+
+```bash
+  bundle exec ruby starter.rb query initial-id
+```
+
+Throws an error: `[TMPRL1100] Nondeterminism error: Activity type of scheduled event 'PrePatch' does not match activity type of activity command 'PostPatch'`
+
+All workflows in "Stage 2" and any new workflows can be queried.
+
+Now let's start another workflow with this patch deprecated code:
+
+```bash
+  bundle exec ruby starter.rb start deprecated-id
+```
+
+This will output `Started workflow with id deprecated-id`.
+Now query the patched workflow from "Stage 2"
+
+```bash
+  bundle exec ruby starter.rb query patched-id
+```
+
+This will output "Query result for id patched-id: post-patch".
+
+And if we execute a query against the latest workflow:
+
+```bash
+  bundle exec ruby starter.rb query deprecated-id
+```
+
+As expected, this will output "Query result for id deprecated-id: post-patch".
+
+## Stage 4
+
+Once we know we don't even have any workflows running on "Stage 2" or before (i.e. the workflow with the patch with both code paths), we can just remove the patch deprecation altogether.
+To use the patch complete workflow, stop the worker from before and start it again with:
+
+```bash
+  bundle exec ruby worker.rb complete
+```
+
+All workflows in "Stage 3" and any new workflows will work.
+Now let's start another workflow with this patch complete code:
+
+```bash
+  bundle exec ruby starter.rb start complete-id
+```
+
+Now query the patch deprecated workflow that's still running:
+
+```bash
+  bundle exec ruby starter.rb query deprecated-id
+```
+
+This will output "Query result for id deprecated-id: post-patch".
+
+And if we execute a query against the latest workflow:
+
+```bash
+  bundle exec ruby starter.rb query completed-id
+```
+
+As expected, this will output "Query result for id complete-id: post-patch".
+
+Following these stages, we have successfully altered our workflow code.

patching/my_activities.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+
+module Patching
+  module MyActivities
+    class PrePatch < Temporalio::Activity::Definition
+      def execute
+        'pre-patch'
+      end
+    end
+
+    class PostPatch < Temporalio::Activity::Definition
+      def execute
+        'post-patch'
+      end
+    end
+  end
+end

patching/starter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+
+# Create a client
+client = Temporalio::Client.connect('localhost:7233', 'default')
+
+command, workflow_id = ARGV
+raise('Missing command argument. Valid commands are start and query') if command.nil?
+raise('Missing workflow_id') if workflow_id.nil?
+
+case command
+when 'start'
+  # Start a workflow with the given id
+  client.start_workflow(
+    :MyWorkflow,
+    id: workflow_id,
+    task_queue: 'patching-sample'
+  )
+  puts "Started workflow with id #{workflow_id}"
+when 'query'
+  # Obtain a workflow handle for the given id and query the result
+  handle = client.workflow_handle(workflow_id)
+  result = handle.query(:result)
+  puts "Query result for id #{workflow_id}: #{result}"
+else
+  raise('Invalid command. Valid commands are start and query')
+end

patching/worker.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'my_activities'
+require_relative 'workflow_1_initial'
+require_relative 'workflow_2_patched'
+require_relative 'workflow_3_deprecated'
+require_relative 'workflow_4_complete'
+require 'logger'
+require 'temporalio/client'
+require 'temporalio/worker'
+
+# Create a Temporal client
+client = Temporalio::Client.connect(
+  'localhost:7233',
+  'default',
+  logger: Logger.new($stdout, level: Logger::INFO)
+)
+
+workflow_versions = {
+  'initial' => Patching::MyWorkflow1Initial,
+  'patched' => Patching::MyWorkflow2Patched,
+  'deprecated' => Patching::MyWorkflow3Deprecated,
+  'complete' => Patching::MyWorkflow4Complete
+}
+
+# Select which version of the workflow the worker should use
+workflow_version = ARGV.first || raise('Missing argument for workflow version')
+workflow = workflow_versions[workflow_version] ||
+           raise("Unrecognized workflow #{workflow_version}. Accepted values are #{workflow_versions.keys.join(', ')}")
+# Create worker with the activities and workflow
+worker = Temporalio::Worker.new(
+  client:,
+  task_queue: 'patching-sample',
+  activities: [Patching::MyActivities::PrePatch, Patching::MyActivities::PostPatch],
+  workflows: [
+    workflow
+  ]
+)
+
+# Run the worker until SIGINT
+puts 'Starting worker (ctrl+c to exit)'
+worker.run(shutdown_signals: ['SIGINT'])

patching/workflow_1_initial.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow1Initial < Temporalio::Workflow::Definition
+    workflow_name :MyWorkflow
+    workflow_query_attr_reader :result
+
+    def execute
+      @result = Temporalio::Workflow.execute_activity(
+        MyActivities::PrePatch,
+        start_to_close_timeout: 5 * 60
+      )
+    end
+  end
+end

patching/workflow_2_patched.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow2Patched < Temporalio::Workflow::Definition
+    workflow_name :MyWorkflow
+    workflow_query_attr_reader :result
+
+    def execute
+      # Decide which activity to use based on workflow's patch status
+      @result = if Temporalio::Workflow.patched(:my_patch)
+                  Temporalio::Workflow.execute_activity(
+                    MyActivities::PostPatch,
+                    start_to_close_timeout: 5 * 60
+                  )
+                else
+                  Temporalio::Workflow.execute_activity(
+                    MyActivities::PrePatch,
+                    start_to_close_timeout: 5 * 60
+                  )
+                end
+    end
+  end
+end

patching/workflow_3_deprecated.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow3Deprecated < Temporalio::Workflow::Definition
+    workflow_name :MyWorkflow
+    workflow_query_attr_reader :result
+
+    def execute
+      Temporalio::Workflow.deprecate_patch(:my_patch)
+      @result = Temporalio::Workflow.execute_activity(
+        MyActivities::PostPatch,
+        start_to_close_timeout: 5 * 60
+      )
+    end
+  end
+end

patching/workflow_4_complete.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow4Complete < Temporalio::Workflow::Definition
+    workflow_name :MyWorkflow
+    workflow_query_attr_reader :result
+
+    def execute
+      @result = Temporalio::Workflow.execute_activity(
+        MyActivities::PostPatch,
+        start_to_close_timeout: 5 * 60
+      )
+    end
+  end
+end