temporalio 0.3.0 → 0.5.0

data/Cargo.toml

@@ -13,13 +13,13 @@ license-file = "LICENSE"
 
 [workspace.dependencies]
 derive_builder = "0.20"
-derive_more = { version = "1.0", features = ["constructor", "display", "from", "into", "debug"] }
+derive_more = { version = "2.0", features = ["constructor", "display", "from", "into", "debug", "try_into"] }
 thiserror = "2"
-tonic = "0.12"
-tonic-build = "0.12"
-opentelemetry = { version = "0.26", features = ["metrics"] }
+tonic = "0.13"
+tonic-build = "0.13"
+opentelemetry = { version = "0.30", features = ["metrics"] }
 prost = "0.13"
 prost-types = "0.13"
 
 [workspace.lints.rust]
-unreachable_pub = "warn"
+unreachable_pub = "warn"

data/Gemfile

@@ -12,6 +12,10 @@ group :development do
   gem 'grpc', '~> 1.69'
   gem 'grpc-tools', '~> 1.69'
   gem 'minitest'
+  # We are intentionally not pinning OTel versions here so that CI tests the latest. This also means that the OTel
+  # contrib library also does not require specific versions, we are relying on the compatibility rigor of OTel.
+  gem 'opentelemetry-api'
+  gem 'opentelemetry-sdk'
   gem 'rake'
   gem 'rake-compiler'
   gem 'rbs', '~> 3.5.3'

data/README.md

@@ -11,15 +11,20 @@ execute asynchronous, long-running business logic in a scalable and resilient wa
 
 Also see:
 
+* [Ruby SDK](https://github.com/temporalio/sdk-ruby)
 * [Ruby Samples](https://github.com/temporalio/samples-ruby)
-* [API Documentation](https://rubydoc.info/gems/temporalio/0.2.0)
+* [API Documentation](https://ruby.temporal.io)
+
+**NOTE: This README is for the current branch and not necessarily what's released on RubyGems.**
 
 ⚠️ 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.
 
-**NOTE: This README is for the current branch and not necessarily what's released on RubyGems.**
+During this time, we are requesting any/all feedback from early adopters. We welcome all forms of suggestions or
+opinions. Please communicate with us on [Slack](https://t.mp/slack) in the `#ruby-sdk` channel or via email at
+`sdk@temporal.io`.
 
 ---
 
@@ -37,7 +42,8 @@ until the SDK is marked stable.
     - [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)
+      - [ActiveModel](#activemodel)
+      - [Converter Hints](#converter-hints)
   - [Workers](#workers)
   - [Workflows](#workflows)
     - [Workflow Definition](#workflow-definition)
@@ -62,6 +68,15 @@ until the SDK is marked stable.
     - [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)
 - [Development](#development)
   - [Build](#build)
@@ -92,8 +107,8 @@ 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 and Linux MUSL do not have gems. See the [Platform Support](#platform-support) section for more
-information.
+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.
@@ -285,57 +300,62 @@ will be tried in order until one accepts (default falls through to the JSON one)
 `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.
 
-##### ActiveRecord and ActiveModel
+**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.
 
-By default, `ActiveRecord` and `ActiveModel` objects do not natively support the `JSON` module. A mixin can be created
-to add this support for `ActiveRecord`, for example:
+##### 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 ActiveRecordJSONSupport
+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)
-      hash = as_json
-      hash[::JSON.create_id] = self.class.name
-      hash.to_json(*args)
+      as_json.to_json(*args)
     end
 
     def self.json_create(object)
+      object = object.dup
       object.delete(::JSON.create_id)
-      ret = new
-      ret.attributes = object
-      ret
+      new(**object.symbolize_keys)
     end
   end
 end
 ```
 
-Similarly, a mixin for `ActiveModel` that adds `attributes` accessors can leverage this same mixin, for example:
+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.
 
-```ruby
-module ActiveModelJSONSupport
-  extend ActiveSupport::Concern
-  include ActiveRecordJSONSupport
+##### Converter Hints
 
-  included do
-    def attributes=(hash)
-      hash.each do |key, value|
-        send("#{key}=", value)
-      end
-    end
+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.
 
-    def attributes
-      instance_values
-    end
-  end
-end
-```
+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.
 
-Now `include ActiveRecordJSONSupport` or `include ActiveModelJSONSupport` will make the models work with Ruby `JSON`
-module and therefore Temporal. Of course any other approach to make the models work with the `JSON` module will work as
-well.
+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
 
@@ -408,7 +428,7 @@ class GreetingWorkflow < Temporalio::Workflow::Definition
       # 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
@@ -480,7 +500,8 @@ definition/behavior of the method:
   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.
+be decorated with different handler types/names in the hierarchy. Workflow handlers (execute or any marked method)
+cannot accept keyword arguments.
 
 #### Running Workflows
 
@@ -608,7 +629,7 @@ Or, say, to wait on the first of 5 activities or a timeout to complete:
 # 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)
+    Temporalio::Workflow.execute_activity(MyActivity, "my-arg-#{i}", schedule_to_close_timeout: 300)
   end
 end
 # Start a timer
@@ -853,7 +874,48 @@ the mock activity class to make it appear as the real name.
 
 #### Workflow Replay
 
-TODO: Workflow replayer not yet implemented
+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.
 
 ### Activities
 
@@ -904,6 +966,7 @@ Some notes about activity definition:
 * `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
 
@@ -987,6 +1050,169 @@ 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.
 
+### 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 durnig a workflow run because it can be side effecting. Workflows and the classes they
+reference should not 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
@@ -1000,21 +1226,27 @@ This SDK is backed by a Ruby C extension written in Rust leveraging the
 [Temporal Rust Core](https://github.com/temporalio/sdk-core). 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. Currently, a gem is not published for
-`aarch64-linux-musl` so Alpine Linux users may need to build from scratch or use a libc-based distro.
+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.1+, but due to [an issue](https://github.com/temporalio/sdk-ruby/issues/162), fibers (and
+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.
 
 ## Development
@@ -1023,16 +1255,18 @@ The SDK works on Ruby 3.1+, but due to [an issue](https://github.com/temporalio/
 
 Prerequisites:
 
-* [Ruby](https://www.ruby-lang.org/) >= 3.1 (i.e. `ruby` and `bundle` on the `PATH`)
+* [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`)
 * 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:
+To build shared library for development use (ensure you have cloned submodules) :
 
     bundle exec rake compile
 
@@ -1064,6 +1298,9 @@ the gem at `lib/temporalio/internal/bridge/3.2/temporalio_bridge.so` and
 
 ### Testing
 
+Note you can set `TEMPORAL_TEST_CLIENT_TARGET_HOST` and `TEMPORAL_TEST_CLIENT_TARGET_NAMESPACE`
+(optional, defaults to 'default') environment variables to use an existing server.
+
 This project uses `minitest`. To test:
 
     bundle exec rake test

data/Rakefile

@@ -94,7 +94,7 @@ Rake::Task[:build].enhance([:copy_parent_files]) do
 end
 
 task :rust_lint do
-  sh 'cargo', 'clippy', '--', '-Dwarnings'
+  sh 'cargo', 'clippy', '-p', 'temporalio_bridge', '--no-deps', '--', '-Dwarnings'
   sh 'cargo', 'fmt', '--check'
 end
 

data/ext/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "temporalio_bridge"
 version = "0.1.0"
-edition = "2021"
+edition = "2024"
 authors = ["Chad Retz <chad@temporal.io>"]
 license = "MIT"
 publish = false
@@ -19,8 +19,9 @@ temporal-client = { version = "0.1.0", path = "./sdk-core/client" }
 temporal-sdk-core = { version = "0.1.0", path = "./sdk-core/core", features = ["ephemeral-server"] }
 temporal-sdk-core-api = { version = "0.1.0", path = "./sdk-core/core-api" }
 temporal-sdk-core-protos = { version = "0.1.0", path = "./sdk-core/sdk-core-protos" }
-tokio = "1.26"
+tokio = "1.37"
+tokio-stream = "0.1"
 tokio-util = "0.7"
-tonic = "0.12"
+tonic = "0.13"
 tracing = "0.1"
 url = "2.2"

data/lib/temporalio/activity/cancellation_details.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'temporalio/error'
+
+module Temporalio
+  module Activity
+    # Details that are set when an activity is cancelled. This is only valid at the time the cancel was received, the
+    # state may change on the server after it is received.
+    class CancellationDetails
+      def initialize(
+        gone_from_server: false,
+        cancel_requested: true,
+        timed_out: false,
+        worker_shutdown: false,
+        paused: false,
+        reset: false
+      )
+        @gone_from_server = gone_from_server
+        @cancel_requested = cancel_requested
+        @timed_out = timed_out
+        @worker_shutdown = worker_shutdown
+        @paused = paused
+        @reset = reset
+      end
+
+      # @return [Boolean] Whether the activity no longer exists on the server (may already be completed or its workflow
+      #   may be completed).
+      def gone_from_server?
+        @gone_from_server
+      end
+
+      # @return [Boolean] Whether the activity was explicitly cancelled.
+      def cancel_requested?
+        @cancel_requested
+      end
+
+      # @return [Boolean] Whether the activity timeout caused activity to be marked cancelled.
+      def timed_out?
+        @timed_out
+      end
+
+      # @return [Boolean] Whether the worker the activity is running on is shutting down.
+      def worker_shutdown?
+        @worker_shutdown
+      end
+
+      # @return [Boolean] Whether the activity was explicitly paused.
+      def paused?
+        @paused
+      end
+
+      # @return [Boolean] Whether the activity was explicitly reset.
+      def reset?
+        @reset
+      end
+    end
+  end
+end

data/lib/temporalio/activity/context.rb

@@ -48,6 +48,12 @@ module Temporalio
         raise NotImplementedError
       end
 
+      # @return [Object, nil] Activity class instance. This should always be present except for advanced cases where the
+      #   definition was manually created without any instance getter/creator.
+      def instance
+        raise NotImplementedError
+      end
+
       # Record a heartbeat on the activity.
       #
       # Heartbeats should be used for all non-immediately-returning, non-local activities and they are required to
@@ -55,7 +61,8 @@ module Temporalio
       # Users do not have to be concerned with burdening the server by calling this too frequently.
       #
       # @param details [Array<Object>] Details to record with the heartbeat.
-      def heartbeat(*details)
+      # @param detail_hints [Array<Object>, nil] Hints to pass to converter.
+      def heartbeat(*details, detail_hints: nil)
         raise NotImplementedError
       end
 
@@ -64,6 +71,14 @@ module Temporalio
         raise NotImplementedError
       end
 
+      # @return [CancellationDetails, nil] Cancellation details if canceled. These are set just before cancellation is
+      #   actually canceled. These details only represent when the cancel was first performed. Once set, this object is
+      #   never mutated. Therefore, the situation on the server may have changed (e.g. unpause), but this still
+      #   represents the values when cancellation first occurred for this attempt.
+      def cancellation_details
+        raise NotImplementedError
+      end
+
       # @return [Cancellation] Cancellation that is canceled when the worker is shutting down. On worker shutdown, this
       #   is canceled, then the `graceful_shutdown_period` is waited (default 0s), then the activity is canceled.
       def worker_shutdown_cancellation
@@ -102,9 +117,16 @@ module Temporalio
       end
 
       # @return [Metric::Meter] Metric meter to create metrics on, with some activity-specific attributes already set.
+      # @raise [RuntimeError] Called within a {Testing::ActivityEnvironment} and it was not set.
       def metric_meter
         raise NotImplementedError
       end
+
+      # @return [Client] Temporal client this activity worker is running in.
+      # @raise [RuntimeError] Called within a {Testing::ActivityEnvironment} and it was not set.
+      def client
+        raise NotImplementedError
+      end
     end
   end
 end