sdk-ruby

KO | EN

gitlite — search

#python #hacktoberfest #typescript #llm #go #android #linux #java #awesome #cli #security #pytorch #mcp #open-source

(★ 202)

Temporal Ruby SDK

파일 탐색기

최종 버전 다운로드 (.zip)

- - rb-sys-protoc.Dockerfile
- - release_verify.rb
- - build-gems.yml
  - changelog.yml
  - ci.yml
  - gems-publish.yml
  - nightly.yml
  - release-publish.yml
  - run-bench.yml
- CODEOWNERS
- dependabot.yml
- - Cargo.toml
  - extconf.rb
  - README.md
  - sdk-core
- - cloud_namespace.rb
  - memory_bench.rb
  - payload_visitor_gen.rb
  - proto_gen.rb
  - simple_bench.rb
- - temporalio.rb
- - temporalio.rbi
- - common.rbs
  - open_telemetry.rbs
  - temporalio.rbs
- - smoke_test_gem.rb
- - activity_info_standalone_test.rb
  - base64_codec.rb
  - cancellation_test.rb
  - client_activity_async_completion_test.rb
  - client_activity_hints_test.rb
  - client_activity_interceptor_chain_test.rb
  - client_activity_test.rb
  - client_cloud_test.rb
  - client_schedule_test.rb
  - client_test.rb
  - client_workflow_interceptor_chain_test.rb
  - client_workflow_test.rb
  - deadlock_test.rb
  - envconfig_test.rb
  - extra_assertions.rb
  - gc_utils.rb
  - plugin_test.rb
  - rbi_parse_test.rb
  - rbi_untyped_count_test.rb
  - runtime_test.rb
  - scoped_logger_test.rb
  - test.rb
  - test_environment_test.rb
  - type_signature_coverage_test.rb
  - worker_activity_test.rb
  - worker_payload_size_limits_test.rb
  - worker_test.rb
  - worker_workflow_activity_test.rb
  - worker_workflow_child_test.rb
  - worker_workflow_external_test.rb
  - worker_workflow_handler_test.rb
  - worker_workflow_nexus_test.rb
  - worker_workflow_priority_test.rb
  - worker_workflow_test.rb
  - worker_workflow_versioning_test.rb
  - workflow_utils.rb
- .rubocop.yml
- .yardopts
- Cargo.lock
- Cargo.toml
- Gemfile
- Gemfile.lock
- Rakefile
- rbs_collection.lock.yaml
- rbs_collection.yaml
- Steepfile
- temporalio.gemspec
.gitattributes
.gitignore
.gitmodules
.protoc-gen-rbi-version
.protoc-version
AGENTS.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/temporalio/sdk-ruby

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd sdk-ruby

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Ruby gem 명령어를 쓰려면 Ruby가 필요합니다.
Go go install 명령어를 쓰려면 Go가 필요합니다.

gem install temporalio

RubyGems에 배포된 패키지를 바로 설치합니다.

go install github.com/coinbase/protoc-gen-rbi@$(cat ../.protoc-gen-rbi-version)

지정된 버전을 바로 다운로드해서 설치합니다. 레포를 직접 클론할 필요가 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Rust

보통

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Rust (rustup) rustup으로 설치하면 cargo도 함께 설치됩니다.

cd temporalio

이 프로젝트의 관련 파일이 하위 폴더 안에 있어서, 먼저 그 폴더로 이동합니다.

cargo build --release

Rust 프로젝트를 컴파일합니다.

cargo run

빌드 후 바로 실행까지 진행합니다.

✅ cargo build가 에러 없이 끝나면 성공입니다. target/ 폴더에 실행 파일이 생성됩니다.

4. Ruby

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Ruby bundle 명령어를 쓰려면 Ruby가 필요합니다.

TEMPORALIO_FIPS=1 bundle exec rb-sys-dock --platform x86_64-linux --ruby-versions 3.4 --build

이 명령어를 터미널에 그대로 입력해 실행하세요.

bundle config --local path $(pwd)/.bundle

이 명령어를 터미널에 그대로 입력해 실행하세요.

bundle install

Gemfile에 명시된 루비 라이브러리를 설치합니다.

bundle exec rake compile

이 명령어를 터미널에 그대로 입력해 실행하세요.

bundle exec rake

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ bundle install이 에러 없이 끝나면 README에 안내된 실행 명령어(예: rails server)로 마저 실행해보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Ruby 3.3 | 3.4 | 4.0](https://img.shields.io/badge/ruby-3.3%20|%203.4%20|%204.0-blue.svg?style=for-the-badge)
[![MIT](https://img.shields.io/github/license/temporalio/sdk-ruby.svg?style=for-the-badge)](https://raw.githubusercontent.com/temporalio/sdk-ruby/main/LICENSE)
[![Gem](https://img.shields.io/gem/v/temporalio?style=for-the-badge)](https://rubygems.org/gems/temporalio)

[Temporal](https://temporal.io/) is a distributed, scalable, durable, and highly available orchestration engine used to
execute asynchronous, long-running business logic in a scalable and resilient way.

**Temporal Ruby SDK** is the framework for authoring workflows and activities using the Ruby programming language.

Also see:

* [Ruby SDK](https://github.com/temporalio/sdk-ruby)
* [Ruby Samples](https://github.com/temporalio/samples-ruby)
* [API Documentation](https://ruby.temporal.io)

**NOTE: This README is for the current branch and not necessarily what's released on RubyGems.**

---

**Contents**

- [Quick Start](#quick-start)
  - [Installation](#installation)
  - [Implementing a Workflow and Activity](#implementing-a-workflow-and-activity)
  - [Running a Worker](#running-a-worker)
  - [Executing a Workflow](#executing-a-workflow)
- [Usage](#usage)
  - [Client](#client)
    - [Cloud Client Using mTLS](#cloud-client-using-mtls)
    - [Cloud Client Using API Key](#cloud-client-using-api-key)
    - [Data Conversion](#data-conversion)
      - [ActiveModel](#activemodel)
      - [Converter Hints](#converter-hints)
  - [Workers](#workers)
  - [Workflows](#workflows)
    - [Workflow Definition](#workflow-definition)
    - [Running Workflows](#running-workflows)
    - [Invoking Activities](#invoking-activities)
    - [Invoking Child Workflows](#invoking-child-workflows)
    - [Timers and Conditions](#timers-and-conditions)
    - [Workflow Fiber Scheduling and Cancellation](#workflow-fiber-scheduling-and-cancellation)
    - [Workflow Futures](#workflow-futures)
    - [Workflow Utilities](#workflow-utilities)
    - [Workflow Exceptions](#workflow-exceptions)
    - [Workflow Logic Constraints](#workflow-logic-constraints)
    - [Workflow Testing](#workflow-testing)
      - [Automatic Time Skipping](#automatic-time-skipping)
      - [Manual Time Skipping](#manual-time-skipping)
      - [Mocking Activities](#mocking-activities)
    - [Workflow Replay](#workflow-replay)
    - [Advanced Workflow Safety and Escaping](#advanced-workflow-safety-and-escaping)
      - [Durable Fiber Scheduler](#durable-fiber-scheduler)
      - [Illegal Call Tracing](#illegal-call-tracing)
  - [Activities](#activities)
    - [Activity Definition](#activity-definition)
    - [Activity Context](#activity-context)
    - [Activity Heartbeating and Cancellation](#activity-heartbeating-and-cancellation)
    - [Activity Worker Shutdown](#activity-worker-shutdown)
    - [Activity Concurrency and Executors](#activity-concurrency-and-executors)
    - [Activity Testing](#activity-testing)
  - [Telemetry](#telemetry)
    - [Metrics](#metrics)
    - [OpenTelemetry Tracing](#opentelemetry-tracing)
      - [OpenTelemetry Tracing in Workflows](#opentelemetry-tracing-in-workflows)
  - [Rails](#rails)
    - [ActiveRecord](#activerecord)
    - [Lazy/Eager Loading](#lazyeager-loading)
  - [Forking](#forking)
  - [Ractors](#ractors)
  - [Platform Support](#platform-support)
  - [Migration from Coinbase Ruby SDK](#migration-from-coinbase-ruby-sdk)
- [Development](#development)
  - [Build](#build)
    - [Build Platform-specific Gem](#build-platform-specific-gem)
  - [Testing](#testing)
  - [Code Formatting and Type Checking](#code-formatting-and-type-checking)
  - [Proto Generation](#proto-generation)

## Quick Start

### Installation

The Ruby SDK works with Ruby 3.3, 3.4, and 4.0. (If using Fibers, Ruby 3.3.2+ is recommended due to problems with fibers in previous versions.)

Can require in a Gemfile like:

```
gem 'temporalio'
```

Or via `gem install` like:

```
gem install temporalio
```

**NOTE**: Only macOS ARM/x64 and Linux ARM/x64 are supported, and the platform-specific gem chosen is based on when the
gem/bundle install is performed. A source gem is published but cannot be used directly and will fail to build if tried.
MinGW-based Windows is not currently supported. There are caveats with the Google Protobuf dependency on musl-based
Linux. See the [Platform Support](#platform-support) section for more information.

**NOTE**: Due to [an issue](https://github.com/temporalio/sdk-ruby/issues/162), fibers (and `async` gem) are only
supported on Ruby versions 3.3 and newer.

### Implementing a Workflow and Activity

Activities are classes. Here is an example of a simple activity that can be put in `say_hello_activity.rb`:

```ruby
require 'temporalio/activity'

# Implementation of a simple activity
class SayHelloActivity < Temporalio::Activity::Definition
  def execute(name)
    "Hello, #{name}!"
  end
end
```

Workflows are also classes. To create the workflow, put the following in `say_hello_workflow.rb`:

```ruby
require 'temporalio/workflow'
require_relative 'say_hello_activity'

class SayHelloWorkflow < Temporalio::Workflow::Definition
  def execute(name)
    Temporalio::Workflow.execute_activity(
      SayHelloActivity,
      name,
      schedule_to_close_timeout: 300
    )
  end
end
```

This is a simple workflow that executes the `SayHelloActivity` activity.

### Running a Worker

To run this in a worker, put the following in `worker.rb`:

```ruby
require 'temporalio/client'
require 'temporalio/worker'
require_relative 'say_hello_activity'
require_relative 'say_hello_workflow'

# Create a client
client = Temporalio::Client.connect('localhost:7233', 'my-namespace')

# Create a worker with the client, activities, and workflows
worker = Temporalio::Worker.new(
  client:,
  task_queue: 'my-task-queue',
  workflows: [SayHelloWorkflow],
  # There are various forms an activity can take, see "Activities" section for details
  activities: [SayHelloActivity]
)

# Run the worker until SIGINT. This can be done in many ways, see "Workers" section for details.
worker.run(shutdown_signals: ['SIGINT'])
```

Running that will run the worker until Ctrl+C is pressed.

### Executing a Workflow

To start and wait on the workflow result, with the worker program running elsewhere, put the following in
`execute_workflow.rb`:

```ruby
require 'temporalio/client'
require_relative 'say_hello_workflow'

# Create a client
client = Temporalio::Client.connect('localhost:7233', 'my-namespace')

# Run workflow
result = client.execute_workflow(
  SayHelloWorkflow,
  'Temporal', # This is the input to the workflow
  id: 'my-workflow-id',
  task_queue: 'my-task-queue'
)
puts "Result: #{result}"
```

This will output:

```
Result: Hello, Temporal!
```

## Usage

### Client

A client can be created and used to start a workflow or otherwise interact with Temporal. For example:

```ruby
require 'temporalio/client'

# Create a client
client = Temporalio::Client.connect('localhost:7233', 'my-namespace')

# Start a workflow
handle = client.start_workflow(
  MyWorkflow,
  'arg1', 'arg2',
  id: 'my-workflow-id',
  task_queue: 'my-task-queue'
)

# Wait for result
result = handle.result
puts "Result: #{result}"
```

Notes about the above code:

* Temporal clients are not explicitly closed.
* To enable TLS, the `tls` option can be set to `true` or a `Temporalio::Client::Connection::TLSOptions` instance.
* Instead of `start_workflow` + `result` above, `execute_workflow` shortcut can be used if the handle is not needed.
* Both `start_workflow` and `execute_workflow` accept either the workflow class or the string/symbol name of the
  workflow.
* The `handle` above is a `Temporalio::Client::WorkflowHandle` which has several other operations that can be performed
  on a workflow. To get a handle to an existing workflow, use `workflow_handle` on the client.
* Clients are thread safe and are fiber-compatible (but fiber compatibility only supported for Ruby 3.3+ at this time).

#### Cloud Client Using mTLS

Assuming a client certificate is present at `my-cert.pem` and a client key is present at `my-key.pem`, this is how to
connect to Temporal Cloud:

```ruby
require 'temporalio/client'

# Create a client
client = Temporalio::Client.connect(
  'my-namespace.a1b2c.tmprl.cloud:7233',
  'my-namespace.a1b2c',
  tls: Temporalio::Client::Connection::TLSOptions.new(
    client_cert: File.read('my-cert.pem'),
    client_private_key: File.read('my-key.pem')
  ))
```

#### Cloud Client Using API Key

Assuming the API key is 'my-api-key', this is how to connect to Temporal cloud:

```ruby
require 'temporalio/client'

# Create a client
client = Temporalio::Client.connect(
  'my-namespace.a1b2c.tmprl.cloud:7233',
  'my-namespace.a1b2c',
  api_key: 'my-api-key'
  tls: true
)
```

#### Data Conversion

Data converters are used to convert raw Temporal payloads to/from actual Ruby types. A custom data converter can be set
via the `data_converter` keyword argument when creating a client. Data converters are a combination of payload
converters, payload codecs, and failure converters. Payload converters convert Ruby values to/from serialized bytes.
Payload codecs convert bytes to bytes (e.g. for compression or encryption). Failure converters convert exceptions
to/from serialized failures.

Data converters are in the `Temporalio::Converters` module. The default data converter uses a default payload converter,
which supports the following types:

* `nil`
* "bytes" (i.e. `String` with `Encoding::ASCII_8BIT` encoding)
* `Google::Protobuf::MessageExts` instances
* [JSON module](https://docs.ruby-lang.org/en/master/JSON.html) for everything else

This means that normal Ruby objects will use `JSON.generate` when serializing and `JSON.parse` when deserializing (with
`create_additions: true` set by default). So a Ruby object will often appear as a hash when deserialized. Also, hashes
that are passed in with symbol keys end up with string keys when deserialized. While "JSON Additions" are supported, it
is not cross-SDK-language compatible since this is a Ruby-specific construct.

The default payload converter is a collection of "encoding payload converters". On serialize, each encoding converter
will be tried in order until one accepts (default falls through to the JSON one). The encoding converter sets an
`encoding` metadata value which is used to know which converter to use on deserialize. Custom encoding converters can be
created, or even the entire payload converter can be replaced with a different implementation.

**NOTE:** For ActiveRecord, or other general/ORM models that are used for a different purpose, it is not recommended to
try to reuse them as Temporal models. Eventually model purposes diverge and models for a Temporal workflows/activities
should be specific to their use for clarity and compatibility reasons. Also many Ruby ORMs do many lazy things and
therefore provide unclear serialization semantics. Instead, consider having models specific for workflows/activities and
translate to/from existing models as needed. See the next section on how to do this with ActiveModel objects.

##### ActiveModel

By default, ActiveModel objects do not natively support the `JSON` module. A mixin can be created to add this support
for ActiveRecord, for example:

```ruby
module ActiveModelJSONSupport
  extend ActiveSupport::Concern
  include ActiveModel::Serializers::JSON

included do
    def as_json(*)
      super.merge(::JSON.create_id => self.class.name)
    end

def to_json(*args)
      as_json.to_json(*args)
    end

def self.json_create(object)
      object = object.dup
      object.delete(::JSON.create_id)
      new(**object.symbolize_keys)
    end
  end
end
```

Now if `include ActiveModelJSONSupport` is present on any ActiveModel class, on serialization `to_json` will be used
which will use `as_json` which calls the super `as_json` but also includes the fully qualified class name as the JSON
`create_id` key. On deserialization, Ruby JSON then uses this key to know what class to call `json_create` on.

##### Converter Hints

In most places where objects are converted to payloads or vice versa, a "hint" can be provided to tell the converter
something else about the object/payload to assist conversion. The default converters ignore these hints, but custom
converters can be written to take advantage of them. For example, hints may be used to provide a custom converter the
Ruby type to deserialize a payload into.

These hints manifest themselves various ways throughout the API. The most obvious way is when making definitions. An
activity can define `activity_arg_hint` (which accepts multiple) and/or `activity_result_hint` for activity-level hints.
Similarly, a workflow can define `workflow_arg_hint` and/or `workflow_result_hint` for workflow-level hints.
`workflow_signal`, `workflow_query`, and `workflow_update` all similarly accept `arg_hints` and `result_hint` (except
signal of course). These definition-level hints are passed to converters both from the caller side and the
implementation side.

There are some advanced payload uses in the SDK that do not currently have a way to set hints. These include
workflow/schedule memo, workflow get/upsert memo, and application error details. In some cases, users can use
`Temporalio::Converters::RawValue` and then manually convert with hints. For others, hints can be added as needed,
please open an issue or otherwise contact Temporal.

### Workers

Workers host workflows and/or activities. Here's how to run a worker:

```ruby
require 'temporalio/client'
require 'temporalio/worker'
require 'my_module'

# Create a client
client = Temporalio::Client.connect('localhost:7233', 'my-namespace')

# Create a worker with the client, activities, and workflows
worker = Temporalio::Worker.new(
  client:,
  task_queue: 'my-task-queue',
  workflows: [MyModule::MyWorkflow],
  # There are various forms an activity can take, see "Activities" section for details
  activities: [MyModule::MyActivity]
)

# Run the worker until block complete
worker.run do
  something_that_waits_for_completion
end
```

Notes about the above code:

* A worker uses the same client that is used for other Temporal things.
* This just shows providing an activity class, but there are other forms, see the "Activities" section for details.
* The worker `run` method accepts an optional `Temporalio::Cancellation` object that can be used to cancel instead or in
  addition to providing a block that waits for completion.
* The worker `run` method accepts a `shutdown_signals` array which will trap the signal and start shutdown when
  received.
* Workers work with threads or fibers (but fiber compatibility only supported for Ruby 3.3+ at this time). Fiber-based
  activities (see "Activities" section) only work if the worker is created within a fiber.
* The `run` method does not return until the worker is shut down. This means even if shutdown is triggered (e.g. via
  `Cancellation` or block completion), it may not return immediately. Activities not completing may hang worker
  shutdown, see the "Activities" section.
* Workers can have many more options not shown here (e.g. tuners and interceptors).
* The `Temporalio::Worker.run_all` class method is available for running multiple workers concurrently.

### Workflows

#### Workflow Definition

Workflows are defined as classes that extend `Temporalio::Workflow::Definition`. The entry point for a workflow is
`execute` and must be defined. Methods for handling signals, queries, and updates are marked with `workflow_signal`,
`workflow_query`, and `workflow_update` just before the method is defined. Here is an example of a workflow definition:

```ruby
require 'temporalio/workflow'

class GreetingWorkflow < Temporalio::Workflow::Definition
  workflow_query_attr_reader :current_greeting

def execute(params)
    loop do
      # Call activity called CreateGreeting to create greeting and store as attribute
      @current_greeting = Temporalio::Workflow.execute_activity(
        CreateGreeting,
        params,
        schedule_to_close_timeout: 300
      )
      Temporalio::Workflow.logger.debug("Greeting set to #{@current_greeting}")

# Wait for param update or complete signal. Note, cancellation can occur by default
      # on wait_condition calls, so Cancellation object doesn't need to be passed
      # explicitly.
      Temporalio::Workflow.wait_condition { @greeting_params_update || @complete }

# If there was an update, exchange and rerun. If it's _only_ a complete, finish
      # workflow with the greeting.
      if @greeting_params_update
        params, @greeting_params_update = @greeting_params_update, nil
      else
        return @current_greeting
      end
    end
  end

workflow_update
  def update_greeting_params(greeting_params_update)
    @greeting_params_update = greeting_params_update
  end

workflow_signal
  def complete_with_greeting
    @complete = true
  end
end
```

Notes about the above code:

* `execute` is the primary entrypoint and its result/exception represents the workflow result/failure.
* `workflow_signal`, `workflow_query` (and the shortcut seen above, `workflow_query_attr_reader`), and `workflow_update`
  implicitly create class methods usable by callers/clients. A workflow definition with no methods actually implemented
  can even be created for use by clients if the workflow is implemented elsewhere and/or in another language.
* Workflow code must be deterministic. See the "Workflow Logic Constraints" section below.
* `execute_activity` accepts either the activity class or the string/symbol for the name.

The following protected class methods are available on `Temporalio::Workflow::Definition` to customize the overall
workflow definition/behavior:

* `workflow_name` - Accepts a string or symbol to change the name. Otherwise the name is defaulted to the unqualified
  class name.
* `workflow_dynamic` - Marks a workflow as dynamic. Dynamic workflows do not have names and handle any workflow that is
  not otherwise registered. A worker can only have one dynamic workflow. It is often useful to use `workflow_raw_args`
  with this.
* `workflow_raw_args` - Have workflow arguments delivered to `execute` (and `initialize` if `workflow_init` in use) as
  `Temporalio::Converters::RawValue`s. These are wrappers for the raw payloads that have not been decoded. They can be
  decoded with `Temporalio::Workflow.payload_converter`. Using this with `*args` splat can be helpful in dynamic
  situations.
* `workflow_failure_exception_type` - Accepts one or more exception classes that will be considered workflow failure
  instead of task failure. See the "Exceptions" section later on what this means. This can be called multiple times.
* `workflow_query_attr_reader` - Is a helper that accepts one or more symbols for attributes to expose as `attr_reader`
  _and_ `workflow_query`. This means it is a superset of `attr_reader` and will not work if also using `attr_reader` or
  `attr_accessor`. If a writer is needed alongside this, use `attr_writer`.

The following protected class methods can be called just before defining instance methods to customize the
definition/behavior of the method:

* `workflow_init` - Mark an `initialize` method as needing the workflow start arguments. Otherwise, `initialize` must
  accept no required arguments. This must be placed above the `initialize` method or it will fail.
* `workflow_signal` - Mark the next method as a workflow signal. The signal name is defaulted to the method name but can
  be customized by the `name` kwarg. See the API documentation for more kwargs that can be set. Return values for
  signals are discarded and exceptions raised in signal handlers are treated as if they occurred in the primary workflow
  method. This also defines a class method of the same name to return the definition for use by clients.
* `workflow_query` - Mark the next method as a workflow query. The query name is defaulted to the method name but can
  be customized by the `name` kwarg. See the API documentation for more kwargs that can be set. The result of the method
  is the result of the query. Queries must never have any side effects, meaning they should never mutate state or try to
  wait on anything. This also defines a class method of the same name to return the definition for use by clients.
* `workflow_update` - Mark the next method as a workflow update. The update name is defaulted to the method name but can
  be customized by the `name` kwarg. See the API documentation for more kwargs that can be set. The result of the method
  is the result of the update. This also defines a class method of the same name to return the definition for use by
  clients.
* `workflow_update_validator` - Mark the next method as a validator to an update. This accepts a symbol for the
  `workflow_update` method it validates. Validators are used to do early rejection of updates and must never have any
  side effects, meaning they should never mutate state or try to wait on anything.

Workflows can be inherited, but subclass workflow-level decorators override superclass ones, and the same method can't
be decorated with different handler types/names in the hierarchy. Workflow handlers (execute or any marked method)
cannot accept keyword arguments.

#### Running Workflows

To start a workflow from a client, you can `start_workflow` and use the resulting handle:

```ruby
# Start the workflow
handle = my_client.start_workflow(
  GreetingWorkflow,
  { salutation: 'Hello', name: 'Temporal' },
  id: 'my-workflow-id',
  task_queue: 'my-task-queue'
)

# Check current greeting via query
puts "Current greeting: #{handle.query(GreetingWorkflow.current_greeting)}"

# Change the params via update
handle.execute_update(
  GreetingWorkflow.update_greeting_params,
  { salutation: 'Aloha', name: 'John' }
)

# Tell it to complete via signal
handle.signal(GreetingWorkflow.complete_with_greeting)

# Wait for workflow result
puts "Final greeting: #{handle.result}"
```

Some things to note about the above code:

* This uses the `GreetingWorkflow` workflow from the previous section.
* The output of this code is "Current greeting: Hello, Temporal!" and "Final greeting: Aloha, John!".
* ID and task queue are required for starting a workflow.
* Signal, query, and update calls here use the class methods created on the definition for safety. So if the
  `update_greeting_params` method didn't exist or wasn't marked as an update, the code will fail client side before even
  attempting the call. Static typing tooling may also take advantage of this for param/result type checking.
* A helper `execute_workflow` method is available on the client that is just `start_workflow` + handle `result`.

#### Invoking Activities

* Activities are executed with `Temporalio::Workflow.execute_activity`, which accepts the activity class or a
  string/symbol activity name.
* Activity options are kwargs on the `execute_activity` method. Either `schedule_to_close_timeout` or
  `start_to_close_timeout` must be set.
* Other options like `retry_policy`, `cancellation_type`, etc can also be set.
* The `cancellation` can be set to a `Cancellation` to send a cancel request to the activity. By default, the
  `cancellation` is the overall `Temporalio::Workflow.cancellation` which is the overarching workflow cancellation.
* Activity failures are raised from the call as `Temporalio::Error::ActivityError`.
* `execute_local_activity` exists with mostly the same options for local activities.

#### Invoking Child Workflows

* Child workflows are started with `Temporalio::Workflow.start_child_workflow`, which accepts the workflow class or
  string/symbol name, arguments, and other options.
* Result for `start_child_workflow` is a `Temporalio::Workflow::ChildWorkflowHandle` which has the `id`, the ability to
  wait on the `result`, and the ability to `signal` the child.
* The `start_child_workflow` call does not complete until the start has been accepted by the server.
* A helper `execute_child_workflow` method is available that is just `start_child_workflow` + handle `result`.

#### Timers and Conditions

* A timer is represented by `Temporalio::Workflow.sleep`.
  * Timers are also started on `Temporalio::Workflow.timeout`.
  * `Kernel.sleep` and `Timeout.timeout` are considered illegal by default.
  * Each timer accepts a `Cancellation`, but if none is given, it defaults to `Temporalio::Workflow.cancellation`.
* `Temporalio::Workflow.wait_condition` accepts a block that waits until the evaluated block result is truthy, then
  returns the value.
  * This function is invoked on each iteration of the internal event loop. This means it cannot have any side effects.
  * This is commonly used for checking if a variable is changed from some other part of a workflow (e.g. a signal
    handler).
  * Each wait conditions accepts a `Cancellation`, but if none is given, it defaults to
    `Temporalio::Workflow.cancellation`.

#### Workflow Fiber Scheduling and Cancellation

Workflows are backed by a custom, deterministic `Fiber::Scheduler`. All fiber calls inside a workflow use this scheduler
to ensure coroutines run deterministically. Although this means that `Kernel.sleep` and `Mutex` and such should work and
since they are Fiber-aware, Temporal intentionally disables their use by default to prevent accidental use. See
"Workflow Logic Constraints" and "Advanced Workflow Safety and Escaping" for more details, and see "Workflow Utilities"
for alternatives.

Every workflow contains a `Temporalio::Cancellation` at `Temporalio::Workflow.cancellation`. This is canceled when the
workflow is canceled. For all workflow calls that accept a cancellation token, this is the default. So if a workflow is
waiting on `execute_activity` and the workflow is canceled, that cancellation will propagate to the waiting activity.

`Cancellation`s may be created to perform cancellation more specifically. A `Cancellation` token derived from the
workflow one can be created via `my_cancel, my_cancel_proc = Cancellation.new(Temporalio::Workflow.cancellation)`. Then
`my_cancel` can be passed as `cancellation` to cancel something more specifically when `my_cancel_proc.call` is invoked.

`Cancellation`s don't have to be derived from the workflow one, they can just be created standalone or "detached". This
is useful for executing, say, a cleanup activity in an `ensure` block that needs to run even on cancel. If the cleanup
activity had instead used the workflow cancellation or one derived from it, then on cancellation it would be cancelled
before it even started.

#### Workflow Futures

`Temporalio::Workflow::Future` can be used for running things in the background or concurrently. This is basically a
safe wrapper around `Fiber.schedule` for starting and `Workflow.wait_condition` for waiting.

Nothing uses futures by default, but they work with all workflow code/constructs. For instance, to run 3 activities and
wait for them all to complete, something like this can be written:

```ruby
# Start 3 activities in background
fut1 = Temporalio::Workflow::Future.new do
  Temporalio::Workflow.execute_activity(MyActivity1, schedule_to_close_timeout: 300)
end
fut2 = Temporalio::Workflow::Future.new do
  Temporalio::Workflow.execute_activity(MyActivity2, schedule_to_close_timeout: 300)
end
fut3 = Temporalio::Workflow::Future.new do
  Temporalio::Workflow.execute_activity(MyActivity3, schedule_to_close_timeout: 300)
end

# Wait for them all to complete
Temporalio::Workflow::Future.all_of(fut1, fut2, fut3).wait

Temporalio::Workflow.logger.debug("Got: #{fut1.result}, #{fut2.result}, #{fut3.result}")
```

Or, say, to wait on the first of 5 activities or a timeout to complete:

```ruby
# Start 5 activities
act_futs = 5.times.map do |i|
  Temporalio::Workflow::Future.new do
    Temporalio::Workflow.execute_activity(MyActivity, "my-arg-#{i}", schedule_to_close_timeout: 300)
  end
end
# Start a timer
sleep_fut = Temporalio::Workflow::Future.new { Temporalio::Workflow.sleep(30) }

# Wait for first act result or sleep fut
act_result = Temporalio::Workflow::Future.any_of(sleep_fut, *act_futs).wait
# Fail if timer done first
raise Temporalio::Error::ApplicationError, 'Timer expired' if sleep_fut.done?
# Print act result otherwise
puts "Act result: #{act_result}"
```

There are several other details not covered here about futures, such as how exceptions are handled, how to use a setter
proc instead of a block, etc. See the API documentation for details.

#### Workflow Utilities

In addition to the pieces documented above, additional methods are available on `Temporalio::Workflow` that can be used
from workflows including:

* `in_workflow?` - Returns `true` if in the workflow or `false` otherwise. This is the only method on the class that can
  be called outside of a workflow without raising an exception.
* `info` - Immutable workflow information.
* `logger` - A Ruby logger that adds contextual information and takes care not to log on replay.
* `metric_meter` - A metric meter for making custom metrics that adds contextual information and takes care not to
  record on replay.
* `random` - A deterministic `Random` instance.
* `memo` - A read-only hash of the memo (updated via `upsert_memo`).
* `search_attributes` - A read-only `SearchAttributes` collection (updated via `upsert_search_attributes`).
* `now` - Current, deterministic UTC time for the workflow.
* `all_handlers_finished?` - Returns true when all signal and update handlers are done. Useful as
  `Temporalio::Workflow.wait_condition { Temporalio::Workflow.all_handlers_finished? }` for making sure not to return
  from the primary workflow method until all handlers are done.
* `patched` and `deprecate_patch` - Support for patch-based versioning inside the workflow. Workers can set
  `patch_activation_callback:` to decide whether a newly introduced patch should activate during rolling deployments.
* `continue_as_new_suggested` - Returns true when the server recommends performing a continue as new.
* `current_update_info` - Returns `Temporalio::Workflow::UpdateInfo` if the current code is inside an update, or nil
  otherwise.
* `external_workflow_handle` - Obtain an handle to an external workflow for signalling or cancelling.
* `payload_converter` - Payload converter if needed for converting raw args.
* `signal_handlers`, `query_handlers`, and `update_handlers` - Hashes for the current set of handlers keyed by name (or
  nil key for dynamic). `[]=` or `store` can be called on these to update the handlers, though defined handlers are
  encouraged over runtime-set ones.

There are also classes for `Temporalio::Workflow::Mutex`, `Temporalio::Workflow::Queue`, and
`Temporalio::Workflow::SizedQueue` that are workflow-safe wrappers around the standard library forms.

`Temporalio::Workflow::ContinueAsNewError` can be raised to continue-as-new the workflow. It accepts positional args and
defaults the workflow to the same as the current, though it can be changed with the `workflow` kwarg. See API
documentation for other details.

#### Workflow Exceptions

* Workflows can raise exceptions to fail the workflow/update or the "workflow task" (i.e. suspend the workflow, retrying
  until code update allows it to continue).
* By default, exceptions that are instances of `Temporalio::Error::Failure` (or `Timeout::Error`) will fail the
  workflow/update with that exception.
  * For failing the workflow/update explicitly with a user exception, explicitly raise
    `Temporalio::Error::ApplicationError`. This can be marked non-retryable or include details as needed.
  * Other exceptions that come from activity execution, child execution, cancellation, etc are already instances of
    `Temporalio::Error::Failure` and will fail the workflow/update if uncaught.
* By default, all other exceptions fail the "workflow task" which means the workflow/update will continually retry until
  the code is fixed. This is helpful for bad code or other non-predictable exceptions. To actually fail the
  workflow/update, use `Temporalio::Error::ApplicationError` as mentioned above.
* By default, all non-deterministic exceptions that are detected internally fail the "workflow task".

The default behavior can be customized at the worker level for all workflows via the
`workflow_failure_exception_types` worker option or per workflow via the `workflow_failure_exception_type` definition
method on the workflow itself. When a workflow encounters a "workflow task" fail (i.e. suspend), it will first check
either of these collections to see if the exception is an instance of any of the types and if so, will turn into a
workflow/update failure. As a special case, when a non-deterministic exception occurs and
`Temporalio::Workflow::NondeterminismError` is assignable to any of the types in the collection, that too
will turn into a workflow/update failure. However unlike other exceptions, non-deterministic exceptions that match
during update handlers become workflow failures not update failures because a non-deterministic exception is an
entire-workflow-failure situation.

#### Workflow Logic Constraints

Temporal Workflows [must be deterministic](https://docs.temporal.io/workflows#deterministic-constraints), which includes
Ruby workflows. This means there are several things workflows cannot do such as:

* Perform IO (network, disk, stdio, etc)
* Access/alter external mutable state
* Do any threading or blocking calls
* Do anything using the system clock (e.g. `Time.Now`)
* Make any random calls
* Make any not-guaranteed-deterministic calls

This means you can't even use logger calls outside of `Temporalio::Workflow.logger` because they use mutexes which may
be hit during periods of high-contention, but they are not completely disabled since users may do quick debugging with
them. See the [Advanced Workflow Safety and Escaping](#advanced-workflow-safety-and-escaping) section if needing to work
around this.

#### Workflow Testing

Workflow testing can be done in an integration-test fashion against a real server. However, it is hard to simulate
timeouts and other long time-based code. Using the time-skipping workflow test environment can help there.

A non-time-skipping `Temporalio::Testing::WorkflowEnvironment` can be started via `start_local` which supports all
standard Temporal features. It is actually a real Temporal server lazily downloaded on first use and run as a
subprocess in the background.

A time-skipping `Temporalio::Testing::WorkflowEnvironment` can be started via `start_time_skipping` which is a
reimplementation of the Temporal server with special time skipping capabilities. This too lazily downloads the process
to run when first called. Note, this class is not thread safe nor safe for use with independent tests. It can be reused,
but only for one test at a time because time skipping is locked/unlocked at the environment level. Note, the
time-skipping test server does not work on ARM-based processors at this time, though macOS ARM users can use it via the
built-in x64 translation in macOS.

##### Automatic Time Skipping

Anytime a workflow result is waited on, the time-skipping server automatically advances to the next event it can. To
manually advance time before waiting on the result of the workflow, the `WorkflowEnvironment.sleep` method can be used
on the environment itself. If an activity is running, time-skipping is disabled.

Here's a simple example of a workflow that sleeps for 24 hours:

```ruby
require 'temporalio/workflow'

class WaitADayWorkflow < Temporalio::Workflow::Definition
  def execute
    Temporalio::Workflow.sleep(1 * 24 * 60 * 60)
    'all done'
  end
end
```

A regular integration test of this workflow on a normal server would be way too slow. However, the time-skipping server
automatically skips to the next event when we wait on the result. Here's a minitest for that workflow:

```ruby
class MyTest < Minitest::Test
  def test_wait_a_day
    Temporalio::Testing::WorkflowEnvironment.start_time_skipping do |env|
      worker = Temporalio::Worker.new(
        client: env.client,
        task_queue: "tq-#{SecureRandom.uuid}",
        workflows: [WaitADayWorkflow],
        workflow_executor: Temporalio::Worker::WorkflowExecutor::ThreadPool.default
      )
      worker.run do
        result = env.client.execute_workflow(
          WaitADayWorkflow,
          id: "wf-#{SecureRandom.uuid}",
          task_queue: worker.task_queue
        )
        assert_equal 'all done', result
      end
    end
  end
end
```

This test will run almost instantly. This is because by calling `execute_workflow` on our client, we are actually
calling `start_workflow` + handle `result`, and `result` automatically skips time as much as it can (basically until the
end of the workflow or until an activity is run).

To disable automatic time-skipping while waiting for a workflow result, run code inside a block passed to
`auto_time_skipping_disabled`.

##### Manual Time Skipping

Until a workflow is waited on, all time skipping in the time-skipping environment is done manually via
`WorkflowEnvironment.sleep`.

Here's a workflow that waits for a signal or times out:

```ruby
require 'temporalio/workflow'

class SignalWorkflow < Temporalio::Workflow::Definition
  def execute
    Temporalio::Workflow.timeout(45) do
      Temporalio::Workflow.wait_condition { @signal_received }
      'got signal'
    rescue Timeout::Error
      'got timeout'
    end
  end

workflow_signal
  def some_signal
    @signal_received = true
  end
end
```

To test a normal signal, you might:

```ruby
class MyTest < Minitest::Test
  def test_signal_workflow_success
    Temporalio::Testing::WorkflowEnvironment.start_time_skipping do |env|
      worker = Temporalio::Worker.new(
        client: env.client,
        task_queue: "tq-#{SecureRandom.uuid}",
        workflows: [SignalWorkflow],
        workflow_executor: Temporalio::Worker::WorkflowExecutor::ThreadPool.default
      )
      worker.run do
        handle = env.client.start_workflow(
          SignalWorkflow,
          id: "wf-#{SecureRandom.uuid}",
          task_queue: worker.task_queue
        )
        handle.signal(SignalWorkflow.some_signal)
        assert_equal 'got signal', handle.result
      end
    end
  end
end
```

But how would you test the timeout part? Like so:

```ruby
class MyTest < Minitest::Test
  def test_signal_workflow_timeout
    Temporalio::Testing::WorkflowEnvironment.start_time_skipping do |env|
      worker = Temporalio::Worker.new(
        client: env.client,
        task_queue: "tq-#{SecureRandom.uuid}",
        workflows: [SignalWorkflow],
        workflow_executor: Temporalio::Worker::WorkflowExecutor::ThreadPool.default
      )
      worker.run do
        handle = env.client.start_workflow(
          SignalWorkflow,
          id: "wf-#{SecureRandom.uuid}",
          task_queue: worker.task_queue
        )
        env.sleep(50)
        assert_equal 'got timeout', handle.result
      end
    end
  end
end
```

This test will run almost instantly. The `env.sleep(50)` manually skips 50 seconds of time, allowing the timeout to be
triggered without actually waiting the full 45 seconds to time out.

##### Mocking Activities

When testing workflows, often you don't want to actually run the activities. Activities are just classes that extend
`Temporalio::Activity::Definition`. Simply write different/empty/fake/asserting ones and pass those to the worker to
have different activities called during the test. You may need to use `activity_name :MyRealActivityClassName` inside
the mock activity class to make it appear as the real name.

#### Workflow Replay

Given a workflow's history, it can be replayed locally to check for things like non-determinism errors. For example,
assuming the `history_json` parameter below is given a JSON string of history exported from the CLI or web UI, the
following function will replay it:

```ruby
def replay_from_json(history_json)
  replayer = Temporalio::Worker::WorkflowReplayer.new(workflows: [MyWorkflow])
  replayer.replay_workflow(Temporalio::WorkflowHistory.from_history_json(history_json))
end
```

If there is a non-determinism, this will raise an exception by default.

Workflow history can be loaded from more than just JSON. It can be fetched individually from a workflow handle, or even
in a list. For example, the following code will check that all workflow histories for a certain workflow type (i.e.
workflow class) are safe with the current workflow code.

```ruby
def check_past_histories(client)
  replayer = Temporalio::Worker::WorkflowReplayer.new(workflows: [MyWorkflow])
  results = replayer.replay_workflows(client.list_workflows("WorkflowType = 'MyWorkflow'").map do |desc|
    client.workflow_handle(desc.id, run_id: desc.run_id).fetch_history
  end)
  results.each { |res| raise res.replay_failure if res.replay_failure }
end
```

But this only raises at the end because by default `replay_workflows` does not raise on failure like `replay_workflow`
does. The `raise_on_replay_failure: true` parameter could be set, or the replay worker can be used to process each one
like so:

```ruby
def check_past_histories(client)
  Temporalio::Worker::WorkflowReplayer.new(workflows: [MyWorkflow]) do |worker|
    client.list_workflows("WorkflowType = 'MyWorkflow'").each do |desc|
      worker.replay_workflow(client.workflow_handle(desc.id, run_id: desc.run_id).fetch_history)
    end
  end
end
```

See the `WorkflowReplayer` API documentation for more details.

#### Advanced Workflow Safety and Escaping

Workflows use a custom fiber scheduler to make fibers durable. There is also call tracing to prevent accidentally making
illegal workflow calls. But sometimes in advanced situations, workarounds may be needed. This section describes advanced
situations working with the workflow Fiber scheduler and illegal call tracer.

##### Durable Fiber Scheduler

By default, Temporal considers `Logger`, `sleep`, `Timeout.timeout`, `Queue`, etc illegal. However, there are cases
where it may be desired for these to work locally inside a workflow such as for logging or other side-effecting,
known-non-deterministic aspects.

Users can pass a block to `Temporalio::Workflow::Unsafe.durable_scheduler_disabled` to not use the durable scheduler.
This should be used any time the scheduler needs to be bypassed, e.g. for local stdout. Not doing this can cause
workflows to get hung in high contention situations. For instance, if there is a logger (that isn't the safe-to-use
`Temporalio::Workflow.logger`) in a workflow, _technically_ Ruby surrounds the IO writes with a mutex and in extreme
high contention that mutex may durably block and then the workflow task may complete causing hung workflows because no
event comes to wake the mutex.

Also, by default anything that relies on IO wait that is not inside `durable_scheduler_disabled` will fail. It is
recommended to put things that need this in `durable_scheduler_disabled`, but if the durable scheduler is still needed
but IO wait is also needed, then a block passed to `Temporalio::Workflow::Unsafe.io_enabled` can be used.

Note `durable_scheduler_disabled` implies `illegal_call_tracing_disabled` (see next section). Many use of 
`durable_scheduler_disabled`, such as for tracing or logging, often surround themselves in a
`unless Temporalio::Workflow.replaying?` block to make sure they don't duplicate the side effects on replay.

##### Illegal Call Tracing

Ruby workflow threads employ a `TracePoint` to catch illegal calls such as `sleep` or `Time.now` or `Thread.new`. The
set of illegal calls can be configured via the `illegal_workflow_calls` parameter when creating a worker. The default
set is at `Temporalio::Worker.default_illegal_workflow_calls`.

When an illegal call is encountered, an exception is thrown. In advanced cases there may be a need to allow an illegal
call that is known to be used deterministically. This code can be in a block passed to
`Temporalio::Workflow::Unsafe.illegal_call_tracing_disabled`. If this has side-effecting behavior that needs to use the
non-durable scheduler, use `durable_scheduler_disabled` instead (which implies this, see previous section).

### Activities

#### Activity Definition

Activities can be defined in a few different ways. They are usually classes, but manual definitions are supported too.

Here is a common activity definition:

```ruby
class FindUserActivity < Temporalio::Activity::Definition
  def execute(user_id)
    User.find(user_id)
  end
end
```

Activities are defined as classes that extend `Temporalio::Activity::Definition` and provide an `execute` method. When
this activity is provided to the worker as a _class_ (e.g. `activities: [FindUserActivity]`), it will be instantiated
for _every attempt_. Many users may prefer using the same instance across activities, for example:

```ruby
class FindUserActivity < Temporalio::Activity
  def initialize(db)
    @db = db
  end

def execute(user_id)
    @db[:users].first(id: user_id)
  end
end
```

When this is provided to a worker as an instance of the activity (e.g. `activities: [FindUserActivity.new(my_db)]`) then
the same instance is reused for each activity.

Some notes about activity definition:

* Temporal activities are identified by their name (or sometimes referred to as "activity type"). This defaults to the
  unqualified class name of the activity, but can be customized by calling the `activity_name` class method.
* Long running activities should heartbeat regularly, see "Activity Heartbeating and Cancellation" later.
* By default every activity attempt is executed in a thread on a thread pool, but fibers are also supported. See
  "Activity Concurrency and Executors" section later for more details.
* Technically an activity definition can be created manually via `Temporalio::Activity::Definition::Info.new` that
  accepts a proc or a block, but the class form is recommended.
* `activity_dynamic` can be used to mark an activity dynamic. Dynamic activities do not have names and handle any
  activity that is not otherwise registered. A worker can only have one dynamic activity.
* `workflow_raw_args` can be used to have activity arguments delivered to `execute` as
  `Temporalio::Converters::RawValue`s. These are wrappers for the raw payloads that have not been converted to types
  (but they have been decoded by the codec if present). They can be converted with `payload_converter` on the context.
* Activities cannot accept keyword arguments.

#### Activity Context

When running in an activity, the `Temporalio::Activity::Context` is available via
`Temporalio::Activity::Context.current` which is backed by a thread/fiber local. In addition to other more advanced
things, this context provides:

* `info` - Information about the running activity.
* `heartbeat` - Method to call to issue an activity heartbeat (see "Activity Heartbeating and Cancellation" later).
* `cancellation` - Instance of `Temporalio::Cancellation` canceled when an activity is canceled (see
  "Activity Heartbeating and Cancellation" later).
* `worker_shutdown_cancellation` - Instance of `Temporalio::Cancellation` canceled when worker is shutting down (see
  "Activity Worker Shutdown" later).
* `logger` - Logger that automatically appends a hash with some activity info to every message.

#### Activity Heartbeating and Cancellation

In order for a non-local activity to be notified of server-side cancellation requests, it must regularly invoke
`heartbeat` on the `Temporalio::Activity::Context` instance (available via `Temporalio::Activity::Context.current`). It
is strongly recommended that all but the fastest executing activities call this function regularly.

In addition to obtaining cancellation information, heartbeats also support detail data that is persisted on the server
for retrieval during activity retry. If an activity calls `heartbeat(123)` and then fails and is retried,
`Temporalio::Activity::Context.current.info.heartbeat_details.first` will be `123`.

An activity can be canceled for multiple reasons, some server-side and some worker side. Server side cancellation
reasons include workflow canceling the activity, workflow completing, or activity timing out. On the worker side, the
activity can be canceled on worker shutdown (see next section). By default cancellation is relayed two ways - by marking
the `cancellation` on `Temporalio::Activity::Context` as canceled, and by issuing a `Thread.raise` or `Fiber.raise` with
the `Temporalio::Error::CanceledError`.

The `raise`-by-default approach was chosen because it is dangerous to the health of the system and the continued use of
worker slots to require activities opt-in to checking for cancellation by default. But if this behavior is not wanted,
`activity_cancel_raise false` class method can be called at the top of the activity which will disable the `raise`
behavior and just set the `cancellation` as canceled.

If needing to shield work from being canceled, the `shield` call on the `Temporalio::Cancellation` object can be used
with a block for the code to be shielded. The cancellation will not take effect on the cancellation object nor the raise
call while the work is shielded (regardless of nested depth). Once the shielding is complete, the cancellation will take
effect, including `Thread.raise`/`Fiber.raise` if that remains enabled.

#### Activity Worker Shutdown

An activity can react to a worker shutdown specifically and also a normal cancellation will be sent. A worker will not
complete its shutdown while an activity is in progress.

Upon worker shutdown, the `worker_shutdown_cancellation` cancellation on `Temporalio::Activity::Context` will be
canceled. Then the worker will wait a for a grace period set by the `graceful_shutdown_period` worker option (default 0)
before issuing actual cancellation to all still-running activities.

Worker shutdown will then wait on all activities to complete. If a long-running activity does not respect cancellation,
the shutdown may never complete.

#### Activity Concurrency and Executors

By default, activities run in the "thread pool executor" (i.e. `Temporalio::Worker::ActivityExecutor::ThreadPool`). This
default is shared across all workers and is a naive thread pool that continually makes threads as needed when none are
idle/available to handle incoming work. If a thread sits idle long enough, it will be killed.

The maximum number of concurrent activities a worker will run at a time is configured via its `tuner` option. The
default is `Temporalio::Worker::Tuner.create_fixed` which defaults to 100 activities at a time for that worker. When
this value is reached, the worker will stop asking for work from the server until there are slots available again.

In addition to the thread pool executor, there is also a fiber executor in the default executor set. To use fibers, call
`activity_executor :fiber` class method at the top of the activity class (the default of this value is `:default` which
is the thread pool executor). Activities can only choose the fiber executor if the worker has been created and run in a
fiber, but thread pool executor is always available. Currently due to
[an issue](https://github.com/temporalio/sdk-ruby/issues/162), workers can only run in a fiber on Ruby versions 3.3 and
newer.

Technically the executor can be customized. The `activity_executors` worker option accepts a hash with the key as the
symbol and the value as a `Temporalio::Worker::ActivityExecutor` implementation. Users should usually not need to
customize this. If general code is needed to run around activities, users should use interceptors instead.

#### Activity Testing

Unit testing an activity can be done via the `Temporalio::Testing::ActivityEnvironment` class. Simply instantiate the
class, then invoke `run` with the activity to test and the arguments to give. The result will be the activity result or
it will raise the error raised in the activity.

The constructor of the environment has multiple keyword arguments that can be set to affect the activity context for the
activity.

#### Standalone Activities

Activities can be started directly from a client, outside the context of any workflow. Standalone activities reuse the
existing `Activity::Definition` class — the same activity code runs whether invoked from a workflow or as a standalone
activity. They are addressed by `activity_id` (with an optional `activity_run_id` for disambiguating re-runs).

Start a standalone activity:

```ruby
handle = client.start_activity(
  MyActivity,
  'some-arg',
  id: 'my-activity-id',
  task_queue: 'my-task-queue',
  start_to_close_timeout: 60
)
result = handle.result   # blocks until the activity completes
```

Or use the execute helper to start and wait:

```ruby
result = client.execute_activity(
  MyActivity, 'some-arg',
  id: 'my-activity-id', task_queue: 'my-task-queue', start_to_close_timeout: 60
)
```

Get a handle to an existing standalone activity to describe, cancel, terminate, or fetch its result:

```ruby
handle = client.activity_handle('my-activity-id')
description = handle.describe       # ActivityExecution::Description
result = handle.result              # blocks until the activity reaches a terminal state
handle.cancel('reason for cancel')  # or
handle.terminate('reason for terminate')
```

List and count standalone activities (visibility queries):

```ruby
client.list_activities('ActivityType="MyActivity"').each { |exec| puts exec.activity_id }
count = client.count_activities('ActivityType="MyActivity"').count
```

Inside an activity body, `Temporalio::Activity::Context.current.info` exposes whether the activity is standalone
or workflow-scheduled:

```ruby
info = Temporalio::Activity::Context.current.info
if info.in_workflow?
  # info.workflow_id, info.workflow_run_id, info.workflow_type are set
else
  # info.activity_run_id is set; workflow_* fields are nil
end
```

### Telemetry

#### Metrics

Metrics can be configured on a `Temporalio::Runtime`. Only one runtime is expected to be created for the entire
application and it should be created before any clients are created. For example, this configures Prometheus to export
metrics at `http://127.0.0.1:9000/metrics`:

```ruby
require 'temporalio/runtime'

Temporalio::Runtime.default = Temporalio::Runtime.new(
  telemetry: Temporalio::Runtime::TelemetryOptions.new(
    metrics: Temporalio::Runtime::MetricsOptions.new(
      prometheus: Temporalio::Runtime::PrometheusMetricsOptions.new(
        bind_address: '127.0.0.1:9000'
      )
    )
  )
)
```

Now every client created will use this runtime. Setting the default will fail if a runtime has already been requested or
a default already set. Technically a runtime can be created without setting the default and be set on each client via
the `runtime` parameter, but this is discouraged because a runtime represents a heavy internal engine not meant to be
created multiple times.

OpenTelemetry metrics can be configured instead by passing `Temporalio::Runtime::OpenTelemetryMetricsOptions` as the
`opentelemetry` parameter to the metrics options. See API documentation for details.

#### OpenTelemetry Tracing

OpenTelemetry tracing for clients, activities, and workflows can be enabled using the
`Temporalio::Contrib::OpenTelemetry::TracingInterceptor`. Specifically, when creating a client, set the interceptor like
so:

```ruby
require 'opentelemetry/api'
require 'opentelemetry/sdk'
require 'temporalio/client'
require 'temporalio/contrib/open_telemetry'

# ... assumes my_otel_tracer_provider is a tracer provider created by the user
my_tracer = my_otel_tracer_provider.tracer('my-otel-tracer')

my_client = Temporalio::Client.connect(
  'localhost:7233', 'my-namespace',
  interceptors: [Temporalio::Contrib::OpenTelemetry::TracingInterceptor.new(my_tracer)]
)
```

Now many high-level client calls and activities/workflows on workers using this client will have spans created on that
OpenTelemetry tracer.

##### OpenTelemetry Tracing in Workflows

OpenTelemetry works by creating spans as necessary and in some cases serializing them to Temporal headers to be
deserialized by workflows/activities to be set on the context. However, OpenTelemetry requires spans to be finished
where they start, so spans cannot be resumed. This is fine for client calls and activity attempts, but Temporal
workflows are resumable functions that may start on a different machine than they complete. Due to this, spans created
by workflows are immediately closed since there is no way for the span to actually span machines. They are also not
created during replay. The spans still become the proper parents of other spans if they are created.

Custom spans can be created inside of workflows using class methods on the
`Temporalio::Contrib::OpenTelemetry::Workflow` module. For example:

```ruby
class MyWorkflow < Temporalio::Workflow::Definition
  def execute
    # Sleep for a bit
    Temporalio::Workflow.sleep(10)
    # Run activity in span
    Temporalio::Contrib::OpenTelemetry::Workflow.with_completed_span(
      'my-span',
      attributes: { 'my-attr' => 'some val' }
    ) do
      # Execute an activity
      Temporalio::Workflow.execute_activity(MyActivity, start_to_close_timeout: 10)
    end
  end
end
```

If this all executes on one worker (because Temporal has a concept of stickiness that caches instances), the span tree
may look like:

```
StartWorkflow:MyWorkflow          <-- created by client outbound
  RunWorkflow:MyWorkflow          <-- created inside workflow on first task
    my-span                       <-- created inside workflow by code
      StartActivity:MyActivity    <-- created inside workflow when first called
        RunActivity:MyActivity    <-- created inside activity attempt 1
    CompleteWorkflow:MyWorkflow   <-- created inside workflow on last task
```

However if, say, the worker crashed during the 10s sleep and the workflow was resumed (i.e. replayed) on another worker,
the span tree may look like:

```
StartWorkflow:MyWorkflow          <-- created by client outbound
  RunWorkflow:MyWorkflow          <-- created by workflow inbound on first task
  my-span                         <-- created inside the workflow
    StartActivity:MyActivity      <-- created by workflow outbound
      RunActivity:MyActivity      <-- created by activity attempt 1 inbound
  CompleteWorkflow:MyWorkflow     <-- created by workflow inbound on last task
```

Notice how the spans are no longer under `RunWorkflow`. This is because spans inside the workflow are not created on
replay, so there is no parent on replay. But there are no orphans because we still have the overarching parent of
`StartWorkflow` that was created by the client and is serialized into Temporal headers so it can always be the parent.

And reminder that `StartWorkflow` and `RunActivity` spans do last the length of their calls (so time to start the
workflow and time to run the activity attempt respectively), but the other spans have no measurable time because they
are created in workflows and closed immediately since long-lived spans cannot work for durable software that may resume
on other machines.

### Rails

Temporal Ruby SDK is a generic Ruby library that can work in any Ruby environment. However, there are some common
conventions for Rails users to be aware of.

See the [rails_app](https://github.com/temporalio/samples-ruby/tree/main/rails_app) sample for an example of using
Temporal from Rails.

#### ActiveRecord

For ActiveRecord, or other general/ORM models that are used for a different purpose, it is not recommended to
try to reuse them as Temporal models. Eventually model purposes diverge and models for a Temporal workflows/activities
should be specific to their use for clarity and compatibility reasons. Also many Ruby ORMs do many lazy things and
therefore provide unclear serialization semantics. Instead, consider having models specific for workflows/activities and
translate to/from existing models as needed. See the [ActiveModel](#activemodel) section on how to do this with
ActiveModel objects.

#### Lazy/Eager Loading

By default, Rails
[eagerly loads](https://guides.rubyonrails.org/v7.2/autoloading_and_reloading_constants.html#eager-loading) all
application code on application start in production, but lazily loads it in non-production environments. Temporal
workflows by default disallow use of IO during the workflow run. With lazy loading enabled in dev/test environments,
when an activity class is referenced in a workflow before it has been explicitly `require`d, it can give an error like:

> Cannot access File path from inside a workflow. If this is known to be safe, the code can be run in a
> Temporalio::Workflow::Unsafe.illegal_call_tracing_disabled block.

This comes from `bootsnap` via `zeitwork` because it is lazily loading a class/module at workflow runtime. It is not
good to lazily load code during a workflow run because it can be side effecting. Workflows and the classes they
reference should be eagerly loaded.

To resolve this, either always eagerly load (e.g. `config.eager_load = true`) or explicitly `require` what is used by a
workflow at the top of the file.

Note, this only affects non-production environments.

### Forking

Objects created with the Temporal Ruby SDK cannot be used across forks. This includes runtimes, clients, and workers. By
default, using `Client.connect` uses `Runtime.default` which is lazily created. If it was already created on the parent,
an exception will occur when trying to reuse it to create clients or workers in a forked child. Similarly any RPC
invocation or worker execution inside of a forked child separate from where the runtime or client or worker were created
will raise an exception.

If forking must be used, make sure Temporal objects are only created _inside_ the fork.

### Ractors

It was an original goal to have workflows actually be Ractors for deterministic state isolation and have the library
support Ractors in general. However, due to the SDK's heavy use of the Google Protobuf library which
[is not Ractor-safe](https://github.com/protocolbuffers/protobuf/issues/19321), the Temporal Ruby SDK does not currently
work with Ractors.

### Platform Support

This SDK is backed by a Ruby C extension written in Rust leveraging the
[Temporal Rust Core](https://github.com/temporalio/sdk-rust). Gems are currently published for the following platforms:

* `aarch64-linux`
* `aarch64-linux-musl`
* `x86_64-linux`
* `x86_64-linux-musl`
* `arm64-darwin`
* `x86_64-darwin`

This means Linux and macOS for ARM and x64 have published gems.

Due to [an issue](https://github.com/temporalio/sdk-ruby/issues/172) with Windows and multi-threaded Rust, MinGW-based
Windows (i.e. `x64-mingw-ucrt`) is not supported. But WSL is supported using the normal Linux gem.

Due to [an issue](https://github.com/protocolbuffers/protobuf/issues/16853) with Google Protobuf, latest Linux versions
of Google Protobuf gems will not work in musl-based environments. Instead use the pure "ruby" platform which will build
the Google Protobuf gem on install (e.g.
`gem 'google-protobuf', force_ruby_platform: RUBY_PLATFORM.include?('linux-musl')` in the `Gemfile`).

At this time a pure source gem is published for documentation reasons, but it cannot be built and will fail if tried.
Building from source requires many files across submodules and requires Rust to be installed. See the [Build](#build)
section for how to build a the repository.

The SDK works on Ruby 3.2+, but due to [an issue](https://github.com/temporalio/sdk-ruby/issues/162), fibers (and
`async` gem) are only supported on Ruby versions 3.3 and newer.

### FIPS Compliance (Experimental)

> **NOTE**: FIPS support is in **Experimental**. It is opt-in, source-build only, and currently exercised on Linux only.

FIPS 140-3 compliant cryptography is available as an **opt-in source build**. The published gems are **not** FIPS
compliant — they use the `ring` backend, which is not FIPS-validated. Because the crypto backend is chosen at compile
time, FIPS cannot be enabled on a precompiled platform gem: you must build the native extension yourself with
`TEMPORALIO_FIPS=1`. When set, the build:

* Selects [`aws-lc-rs`](https://github.com/aws/aws-lc-rs) in FIPS mode (AWS-LC's FIPS 140-3 validated module) for the
  gRPC client and OTLP metric exporter, in place of `ring`.
* Hashes the default worker build id with `Digest::SHA256` instead of MD5.

To produce an installable FIPS gem for your platform:

TEMPORALIO_FIPS=1 bundle exec rb-sys-dock --platform x86_64-linux --ruby-versions 3.4 --build

### Migration from Coinbase Ruby SDK

The [Coinbase Ruby SDK](https://github.com/coinbase/temporal-ruby) predates this official Temporal SDK and has been a
popular approach to developing in Temporal with Ruby. While Temporal encourages users to use the official SDK to get new
features and support, this section covers differences from the Coinbase SDK to help those looking to migrate.

See [this Ruby sample](https://github.com/temporalio/samples-ruby/tree/main/coinbase_ruby) which demonstrates
interoperability between Coinbase Ruby and Temporal Ruby clients, workflows, and activities. Specifically, it discusses
how to disable API class loading on the Coinbase Ruby side if needing to use both dependencies in the same project,
since two sets of API classes cannot both be present.

Migration cannot be done on a live, running workflow. Overall, Coinbase Ruby workflow events are incompatible with
Temporal Ruby workflow events at runtime, so both SDK versions cannot have workers for the same task queue. A live
workflow migration cannot occur, an separate task queue would be needed. However, Coinbase Ruby clients, workflows, and
activities can be used with Temporal Ruby clients, workflows, and activities in either direction. Migrating from the
Coinbase Ruby SDK to the Temporal Ruby SDK would be similar to migrating from Temporal Go SDK to Temporal Java SDK. You
can interact across, but the workflow events are incompatible and therefore the task queues cannot be served by both at
the same time.

Here is an overview of the primary differences between the SDKs:

| Feature | Coinbase Ruby | Temporal Ruby |
| --- | --- | --- |
| Base module | `Temporal::` | `Temporalio::` |
| Client + start workflow | Global `Temporal.configure` + `Temporal.start_workflow` | `Temporalio::Client.connect` + `my_client.start_workflow` |
| Client implementation | Ruby gRPC | Rust gRPC |
| Activity definition | Extend `Temporal::Activity` + impl `execute` | Extend `Temporalio::Activity::Definition` + impl `execute` |
| Workflow definition | Extend `Temporal::Workflow` + impl `execute` | Extend `Temporalio::Workflow::Definition` + impl `execute` |
| Invoke activity from workflow | `MyActivity.execute!` or `workflow.execute_activity!(MyActivity)` | `Workflow.execute_activity(MyActivity)` |
| Handle signal/query/update in workflow | `workflow.on_signal`/`workflow.on_query`/update-unsupported | Decorate with `workflow_signal`/`workflow_query`/`workflow_update` |
| Run worker | `Temporal::Worker.new` + `start` | `Temporalio::Worker.new` + `run` |

This is just a high-level overview, there are many more differences on more specific Temporal components.

## Development

### Build

Prerequisites:

* [Ruby](https://www.ruby-lang.org/) >= 3.2 (i.e. `ruby` and `bundle` on the `PATH`)
* [Rust](https://www.rust-lang.org/) latest stable (i.e. `cargo` on the `PATH`)
* [protoc](https://protobuf.dev/installation/) >= 34.0 (i.e. `protoc` on the `PATH`)
* This repository, cloned recursively
* Change to the `temporalio/` directory

First, install dependencies:

# Optional: Change bundler install path to be local
    bundle config --local path $(pwd)/.bundle
    bundle install

To build shared library for development use (ensure you have cloned submodules) :

bundle exec rake compile

**NOTE**: This will make the current directory usable for the current Ruby version by putting the shared library
`lib/temporalio/internal/bridge/temporalio_bridge.<ext>` in the proper place. But this development shared library may
not work for other Ruby versions or other OS/arch combinations. For that, see "Build Platform-specific Gem" below.

**NOTE**: This is not `compile:dev` because debug-mode in Rust has
[an issue](https://github.com/rust-lang/rust/issues/34283) that causes runtime stack size problems.

**NOTE**: Set `TEMPORALIO_FIPS=1` before compiling to build with the FIPS-mode `aws-lc-rs` crypto backend. See the
[FIPS Compliance](#fips-compliance-beta) section.

To lint, build, and test:

bundle exec rake

#### Build Platform-specific Gem

The standard `bundle exec rake build` will produce a gem in the `pkg` directory, but that gem will not be usable because
the shared library is not present (neither the Rust code nor the compiled form). To create a platform-specific gem that
can be used, `rb-sys-dock` must be run. See the
[Cross-Compilation documentation](https://oxidize-rb.github.io/rb-sys/tutorial/publishing/cross-compilation.html) in the
`rb-sys` repository. For example, running:

bundle exec rb-sys-dock --platform x86_64-linux --ruby-versions 3.2,3.3 --build

Will create a `pkg/temporalio-<version>-x86_64-linux.gem` file that can be used in x64 Linux environments on both Ruby
3.2 and Ruby 3.3 because it contains the shared libraries. For this specific example, the shared libraries are inside
the gem at `lib/temporalio/internal/bridge/3.2/temporalio_bridge.so` and
`lib/temporalio/internal/bridge/3.3/temporalio_bridge.so`.

### Testing

Tests start a local Temporal dev server by default. Set `TEMPORAL_TEST_ENV_CONFIG_SERVER=1` to use
the SDK's environment configuration for an existing server. The standard `TEMPORAL_*` variables
can provide the client configuration directly:

TEMPORAL_TEST_ENV_CONFIG_SERVER=1 \
      TEMPORAL_ADDRESS=my-namespace.tmprl.cloud:7233 \
      TEMPORAL_NAMESPACE=my-namespace \
      TEMPORAL_API_KEY=my-api-key \
      bundle exec rake test

Configuration files and profiles are also supported:

TEMPORAL_TEST_ENV_CONFIG_SERVER=1 TEMPORAL_PROFILE=cloud bundle exec rake test

The envconfig-backed run preserves configured API keys, TLS or mTLS settings, and gRPC metadata. The legacy
`TEMPORAL_TEST_CLIENT_TARGET_HOST` and `TEMPORAL_TEST_CLIENT_TARGET_NAMESPACE` (optional, defaults
to `default`) environment variables remain available when envconfig mode is not selected.

This project uses `minitest`. To test:

bundle exec rake test

Can add options via `TESTOPTS`. E.g. single test:

bundle exec rake test TESTOPTS="--name=test_some_method"

E.g. all starting with prefix:

bundle exec rake test TESTOPTS="--name=/^test_some_method_prefix/"

E.g. all for a class:

bundle exec rake test TESTOPTS="--name=/SomeClassName/"

E.g. show all test names while executing:

bundle exec rake test TESTOPTS="--verbose"

### Code Formatting and Type Checking

This project uses `rubocop`:

bundle exec rake rubocop:autocorrect

This project uses `steep`. First may need the RBS collection:

bundle exec rake rbs:install_collection

Now can run `steep`:

bundle exec rake steep

### Type Signatures (Experimental)

The SDK ships two sets of type signatures:

* **RBS**: Maintained throughout development of the SDK, but only recently made public.
* **RBI**: Sorbet types maintained in parallel with the RBS signatures.

We leverage `protoc` and the `protoc-gen-rbi` plugin to generate RBS and RBI types for all of our Protobuf messages and services.

The RBI signatures are validated at runtime by running the test suite with `TEMPORAL_SORBET_RUNTIME_CHECK=1`, which applies every RBI
signature to the real implementation at runtime via `SigApplicator`.

This is yet another reason to ensure any changes you make have test coverage.

### Proto Generation

Run:

bundle exec rake proto:generate

`proto:generate` now requires `protoc >= 34.0` because we generate RBS alongside the generated Ruby
protobuf files.

We use `protoc-gen-rbi` to generated protobuf RBI.

It can be installed via `go install`:

go install github.com/coinbase/protoc-gen-rbi@$(cat ../.protoc-gen-rbi-version)

sdk-ruby

파일 탐색기

# 설치 가이드

2. 공식 설치 스크립트

3. Rust

4. Ruby

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

sdk-ruby

파일 탐색기

# 설치 가이드

2. 공식 설치 스크립트

3. Rust

4. Ruby

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README