temporalio 0.4.0 → 0.6.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/README.md

@@ -42,7 +42,8 @@ opinions. Please communicate with us on [Slack](https://t.mp/slack) in the `#rub
     - [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)
@@ -60,6 +61,9 @@ opinions. Please communicate with us on [Slack](https://t.mp/slack) in the `#rub
       - [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)
@@ -71,8 +75,13 @@ opinions. Please communicate with us on [Slack](https://t.mp/slack) in the `#rub
     - [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)
@@ -295,57 +304,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
 
@@ -418,7 +432,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
@@ -490,7 +504,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
 
@@ -556,9 +571,7 @@ Some things to note about the above code:
 
 * 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.
+  * `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.
@@ -571,7 +584,10 @@ Some things to note about the above code:
 #### 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.
+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
@@ -663,6 +679,9 @@ from workflows including:
   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.
@@ -699,11 +718,16 @@ 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 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
@@ -906,6 +930,44 @@ 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
@@ -955,6 +1017,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
 
@@ -1154,6 +1217,53 @@ workflow and time to run the activity attempt respectively), but the other spans
 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
@@ -1190,6 +1300,40 @@ 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.
 
+### 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
@@ -1203,9 +1347,11 @@ Prerequisites:
 
 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
 
@@ -1237,6 +1383,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/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,9 +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

@@ -61,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
 
@@ -70,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

data/lib/temporalio/activity/definition.rb

@@ -78,6 +78,21 @@ module Temporalio
 
           @activity_raw_args = value
         end
+
+        # Add activity hints to be passed to converter for activity args.
+        #
+        # @param hints [Array<Object>] Hints to add.
+        def activity_arg_hint(*hints)
+          @activity_arg_hints ||= []
+          @activity_arg_hints.concat(hints)
+        end
+
+        # Set activity result hint to be passed to converter for activity result.
+        #
+        # @param hint [Object] Hint to set.
+        def activity_result_hint(hint)
+          @activity_result_hint = hint
+        end
       end
 
       # @!visibility private
@@ -85,13 +100,20 @@ module Temporalio
         activity_name = @activity_name
         raise 'Cannot have activity name specified for dynamic activity' if activity_name && @activity_dynamic
 
+        # Disallow kwargs in execute parameters
+        if instance_method(:execute).parameters.any? { |t, _| t == :key || t == :keyreq }
+          raise 'Activity execute cannot have keyword arguments'
+        end
+
         # Default to unqualified class name if not dynamic
         activity_name ||= name.to_s.split('::').last unless @activity_dynamic
         {
           activity_name:,
           activity_executor: @activity_executor || :default,
           activity_cancel_raise: @activity_cancel_raise.nil? || @activity_cancel_raise,
-          activity_raw_args: @activity_raw_args.nil? ? false : @activity_raw_args
+          activity_raw_args: @activity_raw_args.nil? ? false : @activity_raw_args,
+          activity_arg_hints: @activity_arg_hints,
+          activity_result_hint: @activity_result_hint
         }
       end
 
@@ -122,6 +144,12 @@ module Temporalio
         # @return [Boolean] Whether to use {Converters::RawValue}s as arguments.
         attr_reader :raw_args
 
+        # @return [Array<Object>, nil] Argument hints.
+        attr_reader :arg_hints
+
+        # @return [Object, nil] Result hint
+        attr_reader :result_hint
+
         # Obtain definition info representing the given activity, which can be a class, instance, or definition info.
         #
         # @param activity [Definition, Class<Definition>, Info] Activity to get info for.
@@ -142,7 +170,9 @@ module Temporalio
               instance: proc { activity.new },
               executor: details[:activity_executor],
               cancel_raise: details[:activity_cancel_raise],
-              raw_args: details[:activity_raw_args]
+              raw_args: details[:activity_raw_args],
+              arg_hints: details[:activity_arg_hints],
+              result_hint: details[:activity_result_hint]
             ) { |*args| Context.current.instance&.execute(*args) }
           when Definition
             details = activity.class._activity_definition_details
@@ -151,7 +181,9 @@ module Temporalio
               instance: activity,
               executor: details[:activity_executor],
               cancel_raise: details[:activity_cancel_raise],
-              raw_args: details[:activity_raw_args]
+              raw_args: details[:activity_raw_args],
+              arg_hints: details[:activity_arg_hints],
+              result_hint: details[:activity_result_hint]
             ) { |*args| Context.current.instance&.execute(*args) }
           when Info
             activity
@@ -167,6 +199,8 @@ module Temporalio
         # @param executor [Symbol] Name of the executor.
         # @param cancel_raise [Boolean] Whether to raise in thread/fiber on cancellation.
         # @param raw_args [Boolean] Whether to use {Converters::RawValue}s as arguments.
+        # @param arg_hints [Array<Object>, nil] Argument hints.
+        # @param result_hint [Object, nil] Result hint.
         # @yield Use this block as the activity.
         def initialize(
           name:,
@@ -174,6 +208,8 @@ module Temporalio
           executor: :default,
           cancel_raise: true,
           raw_args: false,
+          arg_hints: nil,
+          result_hint: nil,
           &block
         )
           @name = name
@@ -184,6 +220,8 @@ module Temporalio
           @executor = executor
           @cancel_raise = cancel_raise
           @raw_args = raw_args
+          @arg_hints = arg_hints
+          @result_hint = result_hint
           Internal::ProtoUtils.assert_non_reserved_name(name)
         end
       end

data/lib/temporalio/activity/info.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'temporalio/activity/context'
+require 'temporalio/internal/proto_utils'
+
 module Temporalio
   module Activity
     Info = Data.define(
@@ -7,9 +10,10 @@ module Temporalio
       :activity_type,
       :attempt,
       :current_attempt_scheduled_time,
-      :heartbeat_details,
       :heartbeat_timeout,
       :local?,
+      :priority,
+      :raw_heartbeat_details,
       :schedule_to_close_timeout,
       :scheduled_time,
       :start_to_close_timeout,
@@ -32,12 +36,15 @@ module Temporalio
     #   @return [Integer] Attempt the activity is on.
     # @!attribute current_attempt_scheduled_time
     #   @return [Time] When the current attempt was scheduled.
-    # @!attribute heartbeat_details
-    #   @return [Array<Object>] Details from the last heartbeat of the last attempt.
     # @!attribute heartbeat_timeout
     #   @return [Float, nil] Heartbeat timeout set by the caller.
     # @!attribute local?
     #   @return [Boolean] Whether the activity is a local activity or not.
+    # @!attribute priority
+    #   @return [Priority] The priority of this activity.
+    # @!attribute raw_heartbeat_details
+    #   @return [Array<Converter::RawValue>] Raw details from the last heartbeat of the last attempt. Can use
+    #     {heartbeat_details} to get lazily-converted values.
     # @!attribute schedule_to_close_timeout
     #   @return [Float, nil] Schedule to close timeout set by the caller.
     # @!attribute scheduled_time
@@ -62,6 +69,20 @@ module Temporalio
     #
     # @note WARNING: This class may have required parameters added to its constructor. Users should not instantiate this
     #   class or it may break in incompatible ways.
-    class Info; end # rubocop:disable Lint/EmptyClass
+    class Info
+      # Convert raw heartbeat details into Ruby types.
+      #
+      # Note, this live-converts every invocation.
+      #
+      # @param hints [Array<Object>, nil] Hints, if any, to assist conversion.
+      # @return [Array<Object>] Converted details.
+      def heartbeat_details(hints: nil)
+        Internal::ProtoUtils.convert_from_payload_array(
+          Context.current.payload_converter,
+          raw_heartbeat_details.map(&:payload),
+          hints:
+        )
+      end
+    end
   end
 end

data/lib/temporalio/activity.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require 'temporalio/activity/cancellation_details'
 require 'temporalio/activity/complete_async_error'
 require 'temporalio/activity/context'
 require 'temporalio/activity/definition'
 require 'temporalio/activity/info'
+require 'temporalio/priority'
 
 module Temporalio
   # All activity related classes.