Temporal Ruby SDK

Because workflow execution must be deterministic, you cannot simply deploy breaking changes (like adding/removing activities or changing the order of operations) without breaking running workflows.

To manage this, use workflow.has_release?(release_name). This method returns a consistent result for a given release_name throughout the lifecycle of a specific workflow execution, allowing you to branch logic based on whether a specific version of your code has been deployed.

class MyWorkflow < Temporal::Workflow
  def execute
    Activity1.execute!

    if workflow.has_release?(:fix_1)
      ActivityNew1.execute!
    end

    # ... logic continues
  end
end

Middleware allows you to execute custom code before or after the execution of workflows or activities (e.g., for logging, error handling, or metrics).

Types of Middleware:

• Activity Middleware: Executed around each activity method.
• Workflow Middleware: Executed around an entire workflow.
• Workflow Task Middleware: Executed around each individual workflow task.

Implementation Pattern: Define a class with a call(metadata) method. You must call yield within call to allow the next middleware or the actual target method to execute.

Note on Order: Middleware added last is the first to execute (it sits at the top of the stack).

class MyMiddleware
  def call(metadata)
    puts "Before execution"
    yield
    puts "After execution"
    result
  end
end

# Adding to a worker
worker.add_activity_middleware(MyMiddleware)

While Temporal.configure sets a global default, you can use Temporal::Configuration objects to manage multiple connections (e.g., connecting to different hosts or using different credentials) within the same application.

config_1 = Temporal::Configuration.new
config_1.host = 'temporal-01'

worker_1 = Temporal::Worker.new(config_1)
client_1 = Temporal::Client.new(config_1)

client_1.start_workflow(MyWorkflow)

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(MyWorkflow)

client_2 = Temporal::Client.new(config_2)
client_2.start_workflow(OtherWorkflow)

To use the Temporal Ruby SDK, include the gem in your Gemfile. You can point directly to the GitHub repository:

gem 'temporal-ruby', github: 'coinbase/temporal-ruby'

A Worker is a process that communicates with the Temporal server to manage the execution of Workflows and Activities. You must register the specific workflows and activities you want the worker to handle before starting it.

Calling worker.start is a blocking operation that takes over the current process until a TERM or INT signal is received.

require 'temporal/worker'

worker = Temporal::Worker.new
worker.register_workflow(HelloWorldWorkflow)
worker.register_activity(SomeActivity)
worker.register_activity(SomeOtherActivity)
worker.start

The Temporal service manages persistence and coordination. To run it locally, use the official Docker Compose configuration:

curl -O https://raw.githubusercontent.com/temporalio/docker-compose/main/docker-compose.yml

docker-compose up

The Temporal Ruby SDK provides a testing framework to run workflows locally.

1. Requirement: You must explicitly require 'temporal/testing' in your test setup (e.g., spec_helper.rb).
2. Unit Testing: Use WorkflowClass.execute_locally(args) to run a workflow locally and pass arguments directly to the #execute method.
3. Integration Testing: Use Temporal::Testing.local! to make all Temporal.start_workflow calls run inline and locally. This can be used with a block to restore original behavior after the test.

# In your test setup
require 'temporal/testing'

# Unit test style
HelloWorldWorkflow.execute_locally(arg1, arg2)

# Integration test style
Temporal::Testing.local! do
  Temporal.start_workflow(HelloWorldWorkflow)
end

In Temporal, Activities perform the actual work (side effects), while Workflows define the high-level orchestration logic.

Important: Workflow code must be deterministic. Do not include network requests, database queries, or non-deterministic logic inside a Temporal::Workflow class, as it may be replayed during execution.

require 'temporal-ruby'

# Define an activity
class HelloActivity < Temporal::Activity
  def execute(name)
    puts "Hello #{name}!"
    nil
  end
end

# Define a workflow that calls the activity
class HelloWorldWorkflow < Temporal::Workflow
  def execute
    HelloActivity.execute!('World')
    nil
  end
end