Infrequent polling benign exception (#42)

* in progress

* add infrequent polling sample with BENIGN exception

* lint fixes

* robocop fixes

* review changes

* review fixes, added test

* lint fixes and test skip on certain envs

Author: THardy98

README.md

@@ -28,6 +28,7 @@ Prerequisites:
 * [context_propagation](context_propagation) - Use interceptors to propagate thread/fiber local data from clients
   through workflows/activities.
 * [message_passing_simple](message_passing_simple) - Simple workflow that accepts signals, queries, and updates.
+* [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.
 * [sorbet_generic](sorbet_generic) - Proof of concept of how to do _advanced_ Sorbet typing with the SDK.
 * [worker_specific_task_queues](worker_specific_task_queues) - Use a unique Task Queue for each Worker to run a sequence of Activities on the same Worker.

polling/infrequent/README.md

@@ -0,0 +1,33 @@
+# Infrequent Polling using Activity Retries
+
+This sample demonstrates how to implement an infrequent polling mechanism using Temporal's automatic Activity Retry feature.
+
+## Purpose
+
+A common requirement for a workflow is to poll an external service until a process is complete. This polling often needs to happen at infrequent intervals (e.g., once a minute or once an hour).
+
+Instead of implementing a `while` loop with a `sleep` call inside the workflow, which can lead to very long-running workflows with large histories, we can offload this logic to Temporal's built-in retry mechanism. This is the more robust and recommended pattern.
+
+This sample shows a workflow that calls an activity. The activity simulates a service that is not immediately available by raising an exception. The workflow configures a `RetryPolicy` on the activity, telling the Temporal Cluster to automatically retry it after a set interval. The workflow itself remains simple and clean, only seeing the final successful result or a terminal failure.
+
+## How to Run
+
+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 `infrequent-polling-sample` task queue.
+
+    ```bash
+    bundle exec ruby polling/infrequent/worker.rb
+    ```
+
+    You will see the worker log messages indicating it is attempting to run the activity. It will try several times, with a 60-second 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 polling/infrequent/starter.rb
+    ```
+
+After about 4 minutes (4 failed attempts with a 60s delay), 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/infrequent/compose_greeting_activity.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+require_relative 'test_service'
+
+module Polling
+  module Infrequent
+    class ComposeGreetingActivity < Temporalio::Activity::Definition
+      def execute(input)
+        activity_info = Temporalio::Activity::Context.current.info
+        TestService.get_service_result(input, activity_info)
+      rescue TestService::TestServiceError => e
+        raise Temporalio::Error::ApplicationError.new(
+          e.message,
+          category: Temporalio::Error::ApplicationError::Category::BENIGN
+        )
+      end
+    end
+  end
+end

polling/infrequent/greeting_workflow.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'compose_greeting_activity'
+
+module Polling
+  module Infrequent
+    class GreetingWorkflow < Temporalio::Workflow::Definition
+      def execute(name)
+        Temporalio::Workflow.execute_activity(
+          ComposeGreetingActivity,
+          { greeting: 'Hello', name: name },
+          retry_policy: Temporalio::RetryPolicy.new(
+            initial_interval: 1, # seconds
+            backoff_coefficient: 1.0
+          ),
+          start_to_close_timeout: 2
+        )
+      end
+    end
+  end
+end

polling/infrequent/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::Infrequent::GreetingWorkflow,
+  'World',
+  id: "infrequent-polling-sample-workflow-id-#{Time.now.to_i}",
+  task_queue: 'infrequent-polling-sample'
+)
+puts "Workflow result: #{result}"

polling/infrequent/test_service.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Polling
+  module Infrequent
+    # 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
+
+        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/infrequent/worker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'greeting_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: 'infrequent-polling-sample',
+  workflows: [Polling::Infrequent::GreetingWorkflow],
+  activities: [Polling::Infrequent::ComposeGreetingActivity]
+)
+
+puts 'Starting worker (ctrl+c to exit)'
+worker.run(shutdown_signals: ['SIGINT'])

test/polling/infrequent/greeting_workflow_test.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'test'
+require 'securerandom'
+require 'temporalio/testing'
+require 'temporalio/worker'
+require 'polling/infrequent/greeting_workflow'
+require 'polling/infrequent/compose_greeting_activity'
+require 'polling/infrequent/test_service'
+
+module Polling
+  module Infrequent
+    class GreetingWorkflowTest < Test
+      def test_workflow_completes_after_polling
+        skip_if_not_x86!
+        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::Infrequent::ComposeGreetingActivity],
+            workflows: [Polling::Infrequent::GreetingWorkflow]
+          )
+
+          handle = env.client.start_workflow(
+            Polling::Infrequent::GreetingWorkflow,
+            'Temporal',
+            id: "wf-#{SecureRandom.uuid}",
+            task_queue: task_queue
+          )
+
+          worker.run do
+            # Advance time forward to allow for the 4 retries (4 * 60s) plus a buffer
+            env.sleep(241)
+
+            # Wait for the workflow to complete and assert its result
+            result = handle.result
+            assert_equal('Hello, Temporal!', result)
+          end
+        end
+      end
+    end
+  end
+end

test/test.rb

@@ -3,4 +3,7 @@
 require 'minitest/autorun'
 
 class Test < Minitest::Test
+  def skip_if_not_x86!
+    skip('Test only supported on x86') unless RbConfig::CONFIG['host_cpu'] == 'x86_64'
+  end
 end