add periodic polling sample

Author: chris-olszewski

README.md

@@ -27,7 +27,9 @@ 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.
+* [polling/frequent](polling/infrequent) - Implement a frequent polling mechanism inside an Activity.
 * [polling/infrequent](polling/infrequent) - Implement an infrequent polling mechanism using Temporal's automatic Activity Retry feature.
+* [polling/periodic_sequence](polling/infrequent) - Implement a periodic polling mechanism using a Child Workflow.
 * [rails_app](rails_app) - Basic Rails API application using Temporal workflows and activities.
 * [saga](saga) - Using undo/compensation using a very simplistic Saga pattern.
 * [sorbet_generic](sorbet_generic) - Proof of concept of how to do _advanced_ Sorbet typing with the SDK.
@@ -40,4 +42,3 @@ Prerequisites:
 To check format and test this repository, run:
 
     bundle exec rake
-

polling/periodic_sequence/README.md

@@ -0,0 +1,36 @@
+# Periodic Polling of a Sequence of Activities
+
+This sample demonstrates how to use a Child Workflow for periodic Activity polling.
+
+This is a rare scenario where polling requires execution of a Sequence of Activities, or Activity arguments need to change between polling retries. For this case we use a Child Workflow to call polling activities a set number of times in a loop and then periodically call Continue-As-New.
+
+## How to Run
+
+To run, first see [README.md](../README.md) for prerequisites.
+
+1. **Start the Worker:**
+
+    Open a terminal and run the following command to start the worker process.
+    The worker will listen for tasks on the `frequent-polling-sample` task queue.
+
+    ```bash
+      bundle exec ruby worker.rb
+    ```
+
+    You will see the worker log messages indicating it is calling the service.
+    It will try several times, with a short delay between each attempt.
+
+2. **Start the Workflow:**
+
+    In a separate terminal, run this command to start the workflow.
+    This script will start the workflow and wait for its completion,
+    printing the final result.
+
+    ```bash
+      bundle exec ruby starter.rb
+    ```
+
+    After a few seconds, the service will succeed.
+    You will see the final result printed in the starter's terminal,
+    and the worker will log the successful completion.
+

polling/periodic_sequence/child_workflow.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'compose_greeting_activity'
+require_relative 'test_service'
+
+module Polling
+  module PeriodicSequence
+    class ChildWorkflow < Temporalio::Workflow::Definition
+      def execute(name)
+        4.times do
+          begin
+            return Temporalio::Workflow.execute_activity(
+              ComposeGreetingActivity,
+              { greeting: 'Hello', name: name },
+              retry_policy: Temporalio::RetryPolicy.new(
+                max_attempts: 1
+              ),
+              start_to_close_timeout: 4
+            )
+          rescue Temporalio::Error::ActivityError
+            Temporalio::Workflow.logger.info('Activity failed')
+          end
+          Temporalio::Workflow.sleep(1)
+        end
+        raise Temporalio::Workflow::ContinueAsNewError, name
+      end
+    end
+  end
+end

polling/periodic_sequence/compose_greeting_activity.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+require_relative 'test_service'
+
+module Polling
+  module PeriodicSequence
+    class ComposeGreetingActivity < Temporalio::Activity::Definition
+      def execute(input)
+        activity_info = Temporalio::Activity::Context.current.info
+        TestService.get_service_result(input, activity_info)
+      end
+    end
+  end
+end

polling/periodic_sequence/greeting_workflow.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'child_workflow'
+
+module Polling
+  module PeriodicSequence
+    class GreetingWorkflow < Temporalio::Workflow::Definition
+      def execute(name)
+        Temporalio::Workflow.execute_child_workflow(ChildWorkflow, name)
+      end
+    end
+  end
+end

polling/periodic_sequence/starter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+require_relative 'greeting_workflow'
+
+# Create a client
+client = Temporalio::Client.connect('localhost:7233', 'default')
+
+# Run workflow
+puts 'Executing workflow'
+result = client.execute_workflow(
+  Polling::PeriodicSequence::GreetingWorkflow,
+  'World',
+  id: "periodic-sequence-polling-sample-workflow-id-#{Time.now.to_i}",
+  task_queue: 'periodic-sequence-polling-sample'
+)
+puts "Workflow result: #{result}"

polling/periodic_sequence/test_service.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Polling
+  module PeriodicSequence
+    # A mock external service with simulated errors.
+    module TestService
+      class TestServiceError < StandardError; end
+
+      @attempts = Hash.new(0)
+      ERROR_ATTEMPTS = 5
+
+      def get_service_result(input, activity_info)
+        workflow_id = activity_info.workflow_id
+        @attempts[workflow_id] ||= 0
+        @attempts[workflow_id] += 1
+
+        # Fake delay to simulate service call
+        sleep 0.01
+        puts "Attempt #{@attempts[workflow_id]} of #{ERROR_ATTEMPTS} to invoke service"
+
+        raise TestServiceError, 'service is down' unless @attempts[workflow_id] == ERROR_ATTEMPTS
+
+        "#{input['greeting']}, #{input['name']}!"
+      end
+      module_function :get_service_result
+    end
+  end
+end

polling/periodic_sequence/worker.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'greeting_workflow'
+require_relative 'child_workflow'
+require_relative 'compose_greeting_activity'
+require 'temporalio/client'
+require 'temporalio/worker'
+
+# Create a client
+client = Temporalio::Client.connect('localhost:7233', 'default')
+
+worker = Temporalio::Worker.new(
+  client:,
+  task_queue: 'periodic-sequence-polling-sample',
+  workflows: [Polling::PeriodicSequence::GreetingWorkflow, Polling::PeriodicSequence::ChildWorkflow],
+  activities: [Polling::PeriodicSequence::ComposeGreetingActivity]
+)
+
+puts 'Starting worker (ctrl+c to exit)'
+worker.run(shutdown_signals: ['SIGINT'])

test/polling/frequent/greeting_workflow_test.rb

@@ -12,7 +12,6 @@ module Polling
   module Frequent
     class GreetingWorkflowTest < Test
       def test_workflow_completes_after_polling
-        # skip_if_not_x86!
         task_queue = "tq-#{SecureRandom.uuid}"
 
         Temporalio::Testing::WorkflowEnvironment.start_local do |env|

test/polling/periodic_sequence/greeting_workflow_test.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'test'
+require 'securerandom'
+require 'temporalio/testing'
+require 'temporalio/worker'
+require 'polling/periodic_sequence/greeting_workflow'
+require 'polling/periodic_sequence/compose_greeting_activity'
+require 'polling/periodic_sequence/test_service'
+
+module Polling
+  module PeriodicSequence
+    class GreetingWorkflowTest < Test
+      def test_workflow_completes_after_polling
+        task_queue = "tq-#{SecureRandom.uuid}"
+
+        Temporalio::Testing::WorkflowEnvironment.start_time_skipping do |env|
+          worker = Temporalio::Worker.new(
+            client: env.client,
+            task_queue: task_queue,
+            activities: [Polling::PeriodicSequence::ComposeGreetingActivity],
+            workflows: [Polling::PeriodicSequence::GreetingWorkflow, Polling::PeriodicSequence::ChildWorkflow]
+          )
+
+          handle = env.client.start_workflow(
+            Polling::PeriodicSequence::GreetingWorkflow,
+            'Temporal',
+            id: "wf-#{SecureRandom.uuid}",
+            task_queue: task_queue
+          )
+
+          worker.run do
+            env.sleep(5)
+            # Wait for the workflow to complete and assert its result
+            result = handle.result
+            assert_equal 'Hello, Temporal!', result
+          end
+
+          child_started_event = handle.fetch_history_events.filter_map do |e|
+            e.child_workflow_execution_started_event_attributes&.workflow_type&.name
+          end.first
+          assert_equal 'ChildWorkflow', child_started_event
+        end
+      end
+    end
+  end
+end