Get latest from upstream

.github/workflows/tests.yml

@@ -37,7 +37,7 @@ jobs:
 
       - name: Start dependencies
         run: |
-          docker-compose \
+          docker compose \
             -f examples/docker-compose.yml \
             up -d
 
@@ -82,4 +82,4 @@ jobs:
         env:
           USE_ERROR_SERIALIZATION_V2: 1
         run: |
-          cd examples && bundle exec rspec
+          cd examples && bundle exec rspec

Gemfile

@@ -1,3 +1,5 @@
 source 'https://rubygems.org'
 
+gem 'google-protobuf', '~> 3.19'
+
 gemspec

README.md

@@ -90,7 +90,8 @@ Temporal::Worker.new(
   workflow_thread_pool_size: 10, # how many threads poll for workflows
   binary_checksum: nil, # identifies the version of workflow worker code
   activity_poll_retry_seconds: 0, # how many seconds to wait after unsuccessful poll for activities
-  workflow_poll_retry_seconds: 0  # how many seconds to wait after unsuccessful poll for workflows
+  workflow_poll_retry_seconds: 0, # how many seconds to wait after unsuccessful poll for workflows
+  activity_max_tasks_per_second: 0 # rate-limit for starting activity tasks (new activities + retries) on the task queue
 )
 ```
 
@@ -178,6 +179,47 @@ Temporal.configure do |config|
 end
 ```
 
+## Configuration
+
+This gem is optimised for the smoothest out-of-the-box experience, which is achieved using a global
+configuration:
+
+```ruby
+Temporal.configure do |config|
+  config.host = '127.0.0.1' # sets global host
+  ...
+end
+
+Temporal::Worker.new # uses global host
+Temporal.start_workflow(...) # uses global host
+```
+
+This will work just fine for simpler use-cases, however at some point you might need to setup
+multiple clients and workers within the same instance of your app (e.g. you have different Temporal
+hosts, need to use different codecs/converters for different parts of your app, etc). Should this be
+the case we recommend using explicit local configurations for each client/worker:
+
+```ruby
+config_1 = Temporal::Configuration.new
+config_1.host = 'temporal-01'
+
+config_2 = Temporal::Configuration.new
+config_2.host = 'temporal-01'
+
+worker_1 = Temporal::Worker.new(config_1)
+worker_2 = Temporal::Worker.new(config_2)
+
+client_1 = Temporal::Client.new(config_1)
+client_1.start_workflow(...)
+
+client_2 = Temporal::Client.new(config_2)
+client_2.start_workflow(...)
+```
+
+*NOTE: Almost all the methods on the `Temporal` module are delegated to the default client that's
+initialized using global configuration. The same methods can be used directly on your own client
+instances.*
+
 ## Workflows
 
 A workflow is defined using pure Ruby code, however it should contain only a high-level
@@ -400,6 +442,36 @@ arguments are identical to the `Temporal.start_workflow` API.
 set it to allow as many invocations as you need. You can also set it to `nil`, which will use a
 default value of 10 years.*
 
+## Middleware
+Middleware sits between the execution of your workflows/activities and the Temporal SDK, allowing you to insert custom code before or after the execution.
+
+### Activity Middleware Stack
+Middleware added to the activity middleware stack will be executed around each activity method. This is useful when you want to perform a certain task before and/or after each activity execution, such as logging, error handling, or measuring execution time.
+
+### Workflow Middleware Stack
+There are actually two types of workflow middleware in Temporal Ruby SDK:
+
+*Workflow Middleware*: This middleware is executed around each entire workflow. This is similar to activity middleware, but for workflows.
+
+*Workflow Task Middleware*: This middleware is executed around each workflow task, of which there will be many for each workflow.
+
+### Example
+To add a middleware, you need to define a class that responds to the call method. Within the call method, you should call yield to allow the next middleware in the stack (or the workflow/activity method itself if there are no more middlewares) to execute. Here's an example:
+
+```
+class MyMiddleware
+  def call(metadata)
+    puts "Before execution"
+    yield
+    puts "After execution"
+    result
+  end
+end
+```
+
+You can add this middleware to the stack like so `worker.add_activity_middleware(MyMiddleware)`
+
+Please note that the order of middleware in the stack matters. The middleware that is added last will be the first one to execute. In the example above, MyMiddleware will execute before any other middleware in the stack.
 
 ## Breaking Changes
 

examples/Gemfile

@@ -2,7 +2,8 @@ source 'https://rubygems.org'
 
 gem 'temporal-ruby', path: '../'
 
-gem 'dry-types', '>= 1.2.0'
-gem 'dry-struct', '~> 1.1.1'
+gem 'dry-types', '>= 1.7.2'
+gem 'dry-struct', '~> 1.6.0'
+gem 'google-protobuf', '~> 3.19'
 
 gem 'rspec', group: :test

examples/bin/update_replay_test_histories

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+# This script regenerates the workflow history files used in the example replay tests
+# under examples/spec/replay/histories. It starts the necessary workflow, sends some
+# signals, awaits workflow completion, then collects the history into JSON and protobuf
+# binary file formats.
+#
+# To use this, start your Temporal server and bin/worker first. This script can then
+# be run without any arguments. It will overwrite existing history files in the tree.
+#
+# NOTE: By default, collected history files contain the host names of the machines
+# where the worker and this script are run because the default identity is pid@hostname.
+# If you'd like, you can override this by setting an identity in the configuration in
+# init.rb.
+
+require_relative "../init"
+require_relative "../workflows/signal_with_start_workflow"
+
+workflow_id = SecureRandom.uuid
+run_id = Temporal.start_workflow(
+  SignalWithStartWorkflow,
+  "hit",
+  options: {
+    workflow_id: workflow_id,
+    timeouts: {
+      execution: 30
+    },
+    signal_name: "miss",
+    signal_input: 1
+  }
+)
+Temporal.logger.info("Started workflow", {workflow_id: workflow_id, run_id: run_id})
+sleep(1)
+Temporal.signal_workflow(SignalWithStartWorkflow, "miss", workflow_id, run_id, 2)
+sleep(1)
+Temporal.signal_workflow(SignalWithStartWorkflow, "hit", workflow_id, run_id, 3)
+Temporal.await_workflow_result(SignalWithStartWorkflow, workflow_id: workflow_id, run_id: run_id)
+
+# Save in JSON, exactly like would be downloaded from Temporal UI
+history_json = Temporal.get_workflow_history_json(workflow_id: workflow_id, run_id: run_id)
+filename = File.expand_path("../spec/replay/histories/signal_with_start.json", File.dirname(__FILE__))
+File.open(filename, "w") do |f|
+  f.write(history_json)
+end
+
+# Save in protobuf binary format
+history_binary = Temporal.get_workflow_history_protobuf(workflow_id: workflow_id, run_id: run_id)
+filename = File.expand_path("../spec/replay/histories/signal_with_start.protobin", File.dirname(__FILE__))
+File.open(filename, "wb") do |f|
+  f.write(history_binary)
+end

examples/docker-compose.yml

@@ -2,7 +2,7 @@ version: '3.5'
 
 services:
   temporal:
-    image: temporalio/auto-setup:latest
+    image: temporalio/auto-setup:1.22.0
     ports:
      - "7233:7233"
     environment:

examples/init.rb

@@ -8,10 +8,13 @@
 
 metrics_logger = Logger.new(STDOUT, progname: 'metrics')
 
+DEFAULT_NAMESPACE = 'ruby-samples'.freeze
+DEFAULT_TASK_QUEUE = 'general'.freeze
+
 Temporal.configure do |config|
   config.host = ENV.fetch('TEMPORAL_HOST', 'localhost')
   config.port = ENV.fetch('TEMPORAL_PORT', 7233).to_i
-  config.namespace = ENV.fetch('TEMPORAL_NAMESPACE', 'ruby-samples')
-  config.task_queue = ENV.fetch('TEMPORAL_TASK_QUEUE', 'general')
+  config.namespace = ENV.fetch('TEMPORAL_NAMESPACE', DEFAULT_NAMESPACE)
+  config.task_queue = ENV.fetch('TEMPORAL_TASK_QUEUE', DEFAULT_TASK_QUEUE)
   config.metrics_adapter = Temporal::MetricsAdapters::Log.new(metrics_logger)
 end

examples/spec/helpers.rb

@@ -21,7 +21,7 @@ def wait_for_workflow_completion(workflow_id, run_id)
   def fetch_history(workflow_id, run_id, options = {})
     connection = Temporal.send(:default_client).send(:connection)
     options = {
-      namespace: Temporal.configuration.namespace,
+      namespace: integration_spec_namespace,
       workflow_id: workflow_id,
       run_id: run_id,
     }.merge(options)
@@ -30,6 +30,10 @@ def fetch_history(workflow_id, run_id, options = {})
   end
 
   def integration_spec_namespace
-    ENV.fetch('TEMPORAL_NAMESPACE', 'ruby-samples')
+    ENV.fetch('TEMPORAL_NAMESPACE', DEFAULT_NAMESPACE)
+  end
+
+  def integration_spec_task_queue
+    ENV.fetch('TEMPORAL_TASK_QUEUE', DEFAULT_TASK_QUEUE)
   end
 end

examples/spec/integration/call_failing_activity_workflow_spec.rb

@@ -1,11 +1,6 @@
 require 'workflows/call_failing_activity_workflow'
 
 describe CallFailingActivityWorkflow, :integration do
-
-  class TestDeserializer
-    include Temporal::Concerns::Payloads
-  end
-
   it 'correctly re-raises an activity-thrown exception in the workflow' do
     workflow_id = SecureRandom.uuid
     expected_message = "a failure message"

examples/spec/integration/converter_spec.rb

@@ -3,22 +3,24 @@
 require 'grpc/errors'
 
 describe 'Converter', :integration do
-  around(:each) do |example|
-    task_queue = Temporal.configuration.task_queue
+  let(:codec) do
+    Temporal::Connection::Converter::Codec::Chain.new(
+      payload_codecs: [
+        Temporal::CryptPayloadCodec.new
+      ]
+    )
+  end
 
+  around(:each) do |example|
     Temporal.configure do |config|
       config.task_queue = 'crypt'
-      config.payload_codec = Temporal::Connection::Converter::Codec::Chain.new(
-        payload_codecs: [
-          Temporal::CryptPayloadCodec.new
-        ]
-      )
+      config.payload_codec = codec
     end
 
     example.run
   ensure
     Temporal.configure do |config|
-      config.task_queue = task_queue
+      config.task_queue = integration_spec_task_queue
       config.payload_codec = Temporal::Configuration::DEFAULT_PAYLOAD_CODEC
     end
   end
@@ -67,8 +69,6 @@
     completion_event = events[:EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED].first
     result = completion_event.workflow_execution_completed_event_attributes.result
 
-    payload_codec = Temporal.configuration.payload_codec
-
-    expect(payload_codec.decodes(result).payloads.first.data).to eq('"Hello World, Tom"')
+    expect(codec.decodes(result).payloads.first.data).to eq('"Hello World, Tom"')
   end
 end

examples/spec/integration/create_schedule_spec.rb

@@ -0,0 +1,87 @@
+require "temporal/errors"
+require "temporal/schedule/backfill"
+require "temporal/schedule/calendar"
+require "temporal/schedule/interval"
+require "temporal/schedule/schedule"
+require "temporal/schedule/schedule_spec"
+require "temporal/schedule/schedule_policies"
+require "temporal/schedule/schedule_state"
+require "temporal/schedule/start_workflow_action"
+
+describe "Temporal.create_schedule", :integration do
+  let(:example_schedule) do
+    workflow_id = SecureRandom.uuid
+    Temporal::Schedule::Schedule.new(
+      spec: Temporal::Schedule::ScheduleSpec.new(
+        calendars: [Temporal::Schedule::Calendar.new(day_of_week: "*", hour: "18", minute: "30")],
+        intervals: [Temporal::Schedule::Interval.new(every: 6000, offset: 300)],
+        cron_expressions: ["@hourly"],
+        jitter: 30,
+        # Set an end time so that the test schedule doesn't run forever
+        end_time: Time.now + 600
+      ),
+      action: Temporal::Schedule::StartWorkflowAction.new(
+        "HelloWorldWorkflow",
+        "Test",
+        options: {
+          workflow_id: workflow_id,
+          task_queue: integration_spec_task_queue
+        }
+      ),
+      policies: Temporal::Schedule::SchedulePolicies.new(
+        overlap_policy: :buffer_one
+      ),
+      state: Temporal::Schedule::ScheduleState.new(
+        notes: "Created by integration test"
+      )
+    )
+  end
+
+  it "can create schedules" do
+    namespace = integration_spec_namespace
+
+    schedule_id = SecureRandom.uuid
+
+    create_response = Temporal.create_schedule(
+      namespace,
+      schedule_id,
+      example_schedule,
+      memo: {"schedule_memo" => "schedule memo value"},
+      trigger_immediately: true,
+      backfill: Temporal::Schedule::Backfill.new(start_time: (Date.today - 90).to_time, end_time: Time.now)
+    )
+    expect(create_response).to(be_an_instance_of(Temporalio::Api::WorkflowService::V1::CreateScheduleResponse))
+
+    describe_response = Temporal.describe_schedule(namespace, schedule_id)
+
+    expect(describe_response.memo).to(eq({"schedule_memo" => "schedule memo value"}))
+    expect(describe_response.schedule.spec.jitter.seconds).to(eq(30))
+    expect(describe_response.schedule.policies.overlap_policy).to(eq(:SCHEDULE_OVERLAP_POLICY_BUFFER_ONE))
+    expect(describe_response.schedule.action.start_workflow.workflow_type.name).to(eq("HelloWorldWorkflow"))
+    expect(describe_response.schedule.state.notes).to(eq("Created by integration test"))
+  end
+
+  it "can create schedules with a minimal set of fields" do
+    namespace = integration_spec_namespace
+    schedule_id = SecureRandom.uuid
+
+    schedule = Temporal::Schedule::Schedule.new(
+      spec: Temporal::Schedule::ScheduleSpec.new(
+        cron_expressions: ["@hourly"],
+        # Set an end time so that the test schedule doesn't run forever
+        end_time: Time.now + 600
+      ),
+      action: Temporal::Schedule::StartWorkflowAction.new(
+        "HelloWorldWorkflow",
+        "Test",
+        options: {task_queue: integration_spec_task_queue}
+      )
+    )
+
+    Temporal.create_schedule(namespace, schedule_id, schedule)
+
+    describe_response = Temporal.describe_schedule(namespace, schedule_id)
+    expect(describe_response.schedule.action.start_workflow.workflow_type.name).to(eq("HelloWorldWorkflow"))
+    expect(describe_response.schedule.policies.overlap_policy).to(eq(:SCHEDULE_OVERLAP_POLICY_SKIP))
+  end
+end