Add activity heartbeat sample. (#36)

Closes #6

Author: robholland

README.md

@@ -19,6 +19,7 @@ Prerequisites:
 ## Samples
 
 <!-- Keep this list in alphabetical order -->
+* [activity_heartbeating](activity_heartbeating) - Demonstrate activity heartbeating and proper cancellation handling.
 * [activity_simple](activity_simple) - Simple workflow that calls two activities.
 * [activity_worker](activity_worker) - Use Ruby activities from a workflow in another language.
 * [client_mtls](client_mtls) - Demonstrates how to use mutual TLS (mTLS) authentication with the Temporal Ruby SDK.

activity_heartbeating/README.md

@@ -0,0 +1,26 @@
+# Activity Heartbeating and Cancellation
+
+This sample demonstrates activity heartbeating and proper cancellation handling. The activity reports progress via heartbeats, which allows it to resume from the last reported progress if it fails and is retried. The sample also demonstrates how to properly handle cancellation in activities.
+
+To run, first see [README.md](../README.md) for prerequisites. Then, in another terminal, start the Ruby worker
+from this directory:
+
+    bundle exec ruby worker.rb
+
+Finally in another terminal, execute the workflow from this directory:
+
+    bundle exec ruby starter.rb
+
+The workflow will start the activity that simulates work by tracking progress from 1 to 100. After 15 seconds, the client will cancel the workflow, which will cancel the activity. The activity will detect the cancellation, log it, and raise a cancellation error.
+
+## What to look for
+
+This sample showcases several important concepts:
+
+1. **Activity Heartbeating**: The activity reports its progress using `context.heartbeat(progress)`. If the activity fails and is retried, it will resume from the last reported progress rather than starting over.
+
+2. **Heartbeat Timeout**: The workflow sets a heartbeat timeout of 3 seconds for the activity, which means the server will consider the activity failed if it doesn't receive a heartbeat for more than 3 seconds.
+
+3. **Cancellation Handling**: The activity checks for cancellation after each progress increment using `context.cancellation.canceled?`. When cancelled, it properly raises a `Temporalio::Error::CanceledError`.
+
+4. **Cancellation Type**: The workflow uses `cancellation_type: :wait_cancellation_completed` to ensure the workflow doesn't proceed until the activity has acknowledged and processed the cancellation. 

activity_heartbeating/my_activities.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+
+module ActivityHeartbeating
+  module MyActivities
+    # Activity that demonstrates progress tracking with heartbeating and cancellation
+    class FakeProgress < Temporalio::Activity::Definition
+      def execute(sleep_interval = 1.0)
+        context = Temporalio::Activity::Context.current
+
+        begin
+          # Allow for resuming from heartbeat details if available
+          starting_point = context.info.heartbeat_details.first || 1
+
+          context.logger.info("Starting activity at progress: #{starting_point}")
+
+          (starting_point..100).each do |progress|
+            # Sleep for the interval - checking cancellation after sleep
+            sleep(sleep_interval)
+
+            context.logger.info("Progress: #{progress}")
+            context.heartbeat(progress)
+          end
+
+          context.logger.info('Fake progress activity completed')
+        rescue Temporalio::Error::CanceledError
+          # This catches the cancel just for demonstration, you usually don't want to catch it
+          context.logger.info('Handling cancellation')
+          raise # Re-raise to properly cancel the activity
+        end
+      end
+    end
+  end
+end

activity_heartbeating/my_workflow.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module ActivityHeartbeating
+  class MyWorkflow < Temporalio::Workflow::Definition
+    def execute
+      # Execute the activity with a 5-minute timeout and 3-second heartbeat timeout
+      Temporalio::Workflow.execute_activity(
+        MyActivities::FakeProgress,
+        1.0, # 1 second sleep interval
+        start_to_close_timeout: 5 * 60,
+        heartbeat_timeout: 3,
+        # Wait for activity cancellation completion
+        cancellation_type: Temporalio::Workflow::ActivityCancellationType::WAIT_CANCELLATION_COMPLETED
+      )
+    rescue Temporalio::Error::ActivityError => e
+      # This catches the cancel just for demonstration, you usually don't want to catch it
+      if e.cause.is_a?(Temporalio::Error::CanceledError)
+        Temporalio::Workflow.logger.info('Workflow cancelled along with its activity')
+      end
+      raise # Re-raise to properly cancel the workflow
+    end
+  end
+end

activity_heartbeating/starter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+require_relative 'my_workflow'
+
+# Create a client
+client = Temporalio::Client.connect('localhost:7233', 'default')
+
+workflow_id = 'activity-heartbeating-workflow-id'
+task_queue = 'activity-heartbeating-sample'
+
+# Start workflow
+puts 'Starting workflow'
+handle = client.start_workflow(
+  ActivityHeartbeating::MyWorkflow,
+  id: workflow_id,
+  task_queue: task_queue
+)
+
+puts "Workflow started with ID: #{workflow_id}"
+puts 'Waiting 15 seconds before cancelling workflow...'
+
+# Wait some time to let the activity make progress
+sleep 15
+
+# Cancel the workflow
+puts 'Cancelling workflow...'
+handle.cancel
+
+begin
+  # Wait for result (which will fail with cancellation)
+  result = handle.result
+  puts "Workflow completed with result: #{result}"
+rescue Temporalio::Error::WorkflowFailedError => e
+  raise unless e.cause.is_a?(Temporalio::Error::CanceledError)
+
+  puts 'Workflow was successfully cancelled'
+end

activity_heartbeating/worker.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'my_activities'
+require_relative 'my_workflow'
+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)
+)
+
+# Create worker with the activities and workflow
+worker = Temporalio::Worker.new(
+  client:,
+  task_queue: 'activity-heartbeating-sample',
+  activities: [ActivityHeartbeating::MyActivities::FakeProgress],
+  workflows: [ActivityHeartbeating::MyWorkflow]
+)
+
+# Run the worker until SIGINT
+puts 'Starting worker (ctrl+c to exit)'
+worker.run(shutdown_signals: ['SIGINT'])

test/activity_heartbeating/my_workflow_test.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'test'
+require 'activity_heartbeating/my_workflow'
+require 'securerandom'
+require 'temporalio/testing'
+require 'temporalio/worker'
+
+module ActivityHeartbeating
+  class MyWorkflowTest < Test
+    def test_workflow
+      # Run test server until completion of the block
+      Temporalio::Testing::WorkflowEnvironment.start_local do |env|
+        # Run worker until completion of the block
+        worker = Temporalio::Worker.new(
+          client: env.client,
+          task_queue: "tq-#{SecureRandom.uuid}",
+          activities: [MyActivities::FakeProgress],
+          workflows: [MyWorkflow]
+        )
+        worker.run do
+          # Start workflow
+          wf = env.client.start_workflow(MyWorkflow, id: "wf-#{SecureRandom.uuid}", task_queue: worker.task_queue)
+
+          # Wait for activity to be scheduled
+          sleep 0.3 until wf.describe.raw_description.pending_activities.any?
+
+          # Cancel workflow
+          wf.cancel
+
+          # Check that it was cancelled
+          assert_raises(Temporalio::Error::WorkflowFailedError, 'Workflow execution canceled') do
+            wf.result
+          end
+        end
+      end
+    end
+  end
+end

test/activity_simple/my_workflow_test.rb

@@ -7,7 +7,7 @@
 require 'temporalio/worker'
 
 module ActivitySimple
-  class ActivitySimpleTest < Test
+  class MyWorkflowTest < Test
     # Demonstrates mocking out activities
     class MockSelectFromDatabase < Temporalio::Activity::Definition
       activity_name :SelectFromDatabase