add frequent and periodic polling samples (#59)

* add frequent polling sample

* add periodic polling sample

* fix readme links

* share mock service between polling examples

Author: chris-olszewski

README.md

@@ -28,7 +28,9 @@ Prerequisites:
 * [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/frequent](polling/frequent) - 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/periodic_sequence) - 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.

polling/frequent/README.md

@@ -0,0 +1,35 @@
+# Frequent Polling Activity
+
+This sample demonstrates how to implement a frequent polling mechanism
+(1 second or faster) inside an Activity.
+The implementation is a loop that polls a service and then sleeps for the poll
+interval (1 second in the sample).
+
+## 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 `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/frequent/compose_greeting_activity.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+require_relative '../test_service'
+
+module Polling
+  module Frequent
+    class ComposeGreetingActivity < Temporalio::Activity::Definition
+      def execute(input)
+        loop do
+          activity_info = Temporalio::Activity::Context.current.info
+          begin
+            return TestService.get_service_result(input, activity_info)
+          rescue TestService::TestServiceError
+            Temporalio::Activity::Context.current.logger.info('Test service was down')
+          end
+          Temporalio::Activity::Context.current.heartbeat
+          sleep 1
+        end
+      end
+    end
+  end
+end

polling/frequent/greeting_workflow.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'compose_greeting_activity'
+
+module Polling
+  module Frequent
+    class GreetingWorkflow < Temporalio::Workflow::Definition
+      def execute(name)
+        Temporalio::Workflow.execute_activity(
+          ComposeGreetingActivity,
+          { greeting: 'Hello', name: name },
+          start_to_close_timeout: 60,
+          heartbeat_timeout: 2
+        )
+      end
+    end
+  end
+end

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

polling/frequent/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: 'frequent-polling-sample',
+  workflows: [Polling::Frequent::GreetingWorkflow],
+  activities: [Polling::Frequent::ComposeGreetingActivity]
+)
+
+puts 'Starting worker (ctrl+c to exit)'
+worker.run(shutdown_signals: ['SIGINT'])

polling/infrequent/compose_greeting_activity.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'temporalio/activity'
-require_relative 'test_service'
+require_relative '../test_service'
 
 module Polling
   module Infrequent

polling/infrequent/test_service.rb

@@ -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/README.md

@@ -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