Temporal Ruby SDK

The Ruby SDK uses a Rust extension to bridge the gap between Tokio (Rust) async and Ruby async. Because C extensions cannot easily turn a non-Ruby thread into a Ruby thread, the bridge uses a "command loop" pattern.

The Command Loop Pattern

1. The Ruby side instantiates and runs a command loop, which consumes a single Ruby thread for the life of the process.
2. This loop unlocks the GVL and waits on a Rust mpsc channel for work.
3. When the Rust side receives work, it re-acquires the GVL and executes a Ruby callback on that specific Ruby thread.

Usage Pattern for Async Calls

To perform an async operation, the bridge follows this flow:

1. Ruby side: Calls a method implemented in Rust. To avoid blocking the entire thread, users should use a mechanism like a Ruby Queue to receive results.
2. Rust side: Spawns a Tokio async task. Once the task completes, it converts the result to a Ruby object and pushes it to the Ruby thread via the command loop.
3. Ruby side: Receives the result (e.g., via queue.pop). If this is called within a Fiber, the Ruby thread remains non-blocking.

Important: The Ruby callback executed by the bridge must be very fast, as it runs serially on the command loop thread.

queue = Queue.new
some_bridge_thing.do_foo(queue)
# If in a Fiber, this pop is non-blocking for the thread
result = queue.pop

Temporal enforces determinism by using a durable fiber scheduler and an illegal call tracer. In advanced scenarios, you may need to bypass these:

1. Bypass Durable Scheduler: Use Temporalio::Workflow::Unsafe.durable_scheduler_disabled when you need to perform non-deterministic side effects (like local stdout logging) that would otherwise hang the workflow due to mutex contention or IO wait.
2. Enable IO Wait: If you need the durable scheduler but also require IO wait, use Temporalio::Workflow::Unsafe.io_enabled.
3. Bypass Illegal Call Tracing: Use Temporalio::Workflow::Unsafe.illegal_call_tracing_disabled to allow specific calls like sleep or Time.now if they are used deterministically.

Note: durable_scheduler_disabled implies illegal_call_tracing_disabled. It is a best practice to wrap these calls in an unless Temporalio::Workflow.replaying? block to prevent side effects from executing during replay.

Data converters translate raw Temporal payloads to and from Ruby types. They consist of:

• Payload Converters: Ruby values $\leftrightarrow$ serialized bytes.
• Payload Codecs: Bytes $\leftrightarrow$ bytes (e.g., compression/encryption).
• Failure Converters: Exceptions $\leftrightarrow$ serialized failures.

Custom converters can be set via the data_converter argument in Temporalio::Client.connect.

The default payload converter supports:

• nil
• String with Encoding::ASCII_8BIT (bytes)
• Google::Protobuf::MessageExts instances
• Everything else via the JSON module.

Note on JSON: When using the default JSON converter, Ruby objects are serialized using JSON.generate. Upon deserialization, they often appear as Hashes. Hashes passed with symbol keys will return with string keys. While "JSON Additions" are supported, they are Ruby-specific and not cross-language compatible.

Workflows can raise exceptions to either fail the workflow/update or to fail the 'workflow task' (which causes a retry of the task until the code is fixed).

Failing a Workflow/Update

To explicitly fail a workflow or update with a user-defined error, raise Temporalio::Error::ApplicationError.

By default, the following will fail the workflow/update:

• Instances of Temporalio::Error::Failure.
• Timeout::Error.
• Exceptions from activity execution, child execution, or cancellation.

Failing a Workflow Task (Retries)

By default, all other exceptions (including non-deterministic exceptions) fail the 'workflow task'. This means the workflow will continually retry the task until the code is updated to fix the error. This is intended for unexpected code errors.

Customizing Failure Behavior

You can customize which exceptions cause a workflow failure (instead of a task retry) at the worker level using the workflow_failure_exception_types option, or per-workflow using the workflow_failure_exception_type definition method.

Workflows are classes that extend Temporalio::Workflow::Definition.

Key Requirements:

• The execute method is the primary entry point and must be defined. Its return value/exception is the workflow's result/failure.
• Workflow code must be deterministic.
• Use Temporalio::Workflow.execute_activity to call activities.
• Use Temporalio::Workflow.wait_condition to pause execution until a state change occurs.

Handling Interactions: Methods marked with the following decorators become accessible to clients:

• workflow_signal: For receiving signals.
• workflow_query: For querying workflow state.
• workflow_update: For sending updates (and receiving results).
• workflow_query_attr_reader: A shortcut for creating query methods for attributes.

require 'temporalio/workflow'

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

  def execute(params)
    loop do
      @current_greeting = Temporalio::Workflow.execute_activity(
        CreateGreeting,
        params,
        schedule_to_close_timeout: 300
      )

      # Wait for signal/update or completion
      Temporalio::Workflow.wait_condition { @greeting_params_update || @complete }

      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