temporalio 0.2.0 → 0.3.0

data/README.md

@@ -1,6 +1,6 @@
-![Temporal Ruby SDK](https://raw.githubusercontent.com/temporalio/assets/main/files/w/ruby.png)
+<div style="overflow: hidden"><img src="https://raw.githubusercontent.com/temporalio/assets/main/files/w/ruby.png" alt="Temporal Ruby SDK" /></div>
 
-![Ruby 3.1 | 3.2 | 3.3](https://img.shields.io/badge/ruby-3.1%20%7C%203.2%20%7C%203.3-blue.svg?style=for-the-badge)
+![Ruby 3.2 | 3.3 | 3.4](https://img.shields.io/badge/ruby-3.2%20|%203.3%20|%203.4-blue.svg?style=for-the-badge)
 [![MIT](https://img.shields.io/github/license/temporalio/sdk-ruby.svg?style=for-the-badge)](LICENSE)
 [![Gem](https://img.shields.io/gem/v/temporalio?style=for-the-badge)](https://rubygems.org/gems/temporalio)
 
@@ -12,18 +12,12 @@ execute asynchronous, long-running business logic in a scalable and resilient wa
 Also see:
 
 * [Ruby Samples](https://github.com/temporalio/samples-ruby)
-* [API Documentation](https://rubydoc.info/gems/temporalio)
+* [API Documentation](https://rubydoc.info/gems/temporalio/0.2.0)
 
 ⚠️ UNDER ACTIVE DEVELOPMENT
 
 This SDK is under active development and has not released a stable version yet. APIs may change in incompatible ways
-until the SDK is marked stable. The SDK has undergone a refresh from a previous unstable version. The last tag before
-this refresh is [v0.1.1](https://github.com/temporalio/sdk-ruby/tree/v0.1.1). Please reference that tag for the
-previous code if needed.
-
-Notably missing from this SDK:
-
-* Workflow workers
+until the SDK is marked stable.
 
 **NOTE: This README is for the current branch and not necessarily what's released on RubyGems.**
 
@@ -35,15 +29,32 @@ Notably missing from this SDK:
 
 - [Quick Start](#quick-start)
   - [Installation](#installation)
-  - [Implementing an Activity](#implementing-an-activity)
-  - [Running a Workflow](#running-a-workflow)
+  - [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)
       - [ActiveRecord and ActiveModel](#activerecord-and-activemodel)
   - [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)
   - [Activities](#activities)
     - [Activity Definition](#activity-definition)
     - [Activity Context](#activity-context)
@@ -65,6 +76,8 @@ Notably missing from this SDK:
 
 ### Installation
 
+The Ruby SDK works with Ruby 3.2, 3.3, and 3.4.
+
 Can require in a Gemfile like:
 
 ```
@@ -85,58 +98,85 @@ 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 an Activity
+### Implementing a Workflow and Activity
 
-Implementing workflows is not yet supported in the Ruby SDK, but implementing activities is.
+Activities are classes. Here is an example of a simple activity that can be put in `say_hello_activity.rb`:
 
-For example, if you have a `SayHelloWorkflow` workflow in another Temporal language that invokes `SayHello` activity on
-`my-task-queue` in Ruby, you can have the following Ruby script:
 
 ```ruby
 require 'temporalio/activity'
-require 'temporalio/cancellation'
-require 'temporalio/client'
-require 'temporalio/worker'
 
 # Implementation of a simple activity
-class SayHelloActivity < Temporalio::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 and activities
+# Create a worker with the client, activities, and workflows
 worker = Temporalio::Worker.new(
   client:,
   task_queue: 'my-task-queue',
-  # There are various forms an activity can take, see specific section for details.
+  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 specific
-# section for details.
+# 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 pressed.
+Running that will run the worker until Ctrl+C is pressed.
 
-### Running a Workflow
+### Executing a Workflow
 
-Assuming that `SayHelloWorkflow` just calls this activity, it can be run like so:
+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',
+  SayHelloWorkflow,
+  'Temporal', # This is the input to the workflow
   id: 'my-workflow-id',
   task_queue: 'my-task-queue'
 )
@@ -163,8 +203,8 @@ client = Temporalio::Client.connect('localhost:7233', 'my-namespace')
 
 # Start a workflow
 handle = client.start_workflow(
-  'SayHelloWorkflow',
-  'Temporal',
+  MyWorkflow,
+  'arg1', 'arg2',
   id: 'my-workflow-id',
   task_queue: 'my-task-queue'
 )
@@ -179,6 +219,8 @@ 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).
@@ -201,6 +243,22 @@ client = Temporalio::Client.connect(
   ))
 ```
 
+#### 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
@@ -215,11 +273,12 @@ 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
+* [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. While
-"JSON Additions" are supported, it is not cross-SDK-language compatible since this is a Ruby-specific construct.
+`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
@@ -280,8 +339,7 @@ well.
 
 ### Workers
 
-Workers host workflows and/or activities. Workflows cannot yet be written in Ruby, but activities can. Here's how to run
-an activity worker:
+Workers host workflows and/or activities. Here's how to run a worker:
 
 ```ruby
 require 'temporalio/client'
@@ -291,11 +349,12 @@ require 'my_module'
 # Create a client
 client = Temporalio::Client.connect('localhost:7233', 'my-namespace')
 
-# Create a worker with the client and activities
+# Create a worker with the client, activities, and workflows
 worker = Temporalio::Worker.new(
   client:,
   task_queue: 'my-task-queue',
-  # There are various forms an activity can take, see specific section for details.
+  workflows: [MyModule::MyWorkflow],
+  # There are various forms an activity can take, see "Activities" section for details
   activities: [MyModule::MyActivity]
 )
 
@@ -311,19 +370,490 @@ Notes about the above code:
 * 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 an `shutdown_signals` array which will trap the signal and start shutdown when
+* 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. data converters and interceptors).
+* 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
 
-⚠️ Workflows cannot yet be implemented Ruby.
+#### 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.
+
+#### 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`.
+  * _Technically_ `Kernel.sleep` and `Timeout.timeout` also delegate to the above calls, but the more explicit workflow
+    forms are encouraged because they accept more options and are not subject to Ruby standard library implementation
+    changes.
+  * 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.
+
+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.
+* `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.
+
+`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
+* Do anything using the system clock (e.g. `Time.Now`)
+* Make any random calls
+* Make any not-guaranteed-deterministic calls
+
+#### 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
+
+TODO: Workflow replayer not yet implemented
 
 ### Activities
 
@@ -334,16 +864,16 @@ Activities can be defined in a few different ways. They are usually classes, but
 Here is a common activity definition:
 
 ```ruby
-class FindUserActivity < Temporalio::Activity
+class FindUserActivity < Temporalio::Activity::Definition
   def execute(user_id)
     User.find(user_id)
   end
 end
 ```
 
-Activities are defined as classes that extend `Temporalio::Activity` 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:
+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
@@ -367,8 +897,13 @@ Some notes about activity definition:
 * 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.new` that accepts a
-  proc or a block, but the class form is recommended.
+* 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.
 
 #### Activity Context
 
@@ -452,6 +987,13 @@ 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.
 
+### 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