temporalio 0.3.0-x86_64-darwin → 0.5.0-x86_64-darwin

data/lib/temporalio/workflow/definition.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'temporalio/internal/proto_utils'
 require 'temporalio/workflow'
 require 'temporalio/workflow/handler_unfinished_policy'
 
@@ -46,6 +47,21 @@ module Temporalio
           @workflow_raw_args = value
         end
 
+        # Add workflow hints to be passed to converter for workflow args.
+        #
+        # @param hints [Array<Object>] Hints to add.
+        def workflow_arg_hint(*hints)
+          @workflow_arg_hints ||= []
+          @workflow_arg_hints.concat(hints)
+        end
+
+        # Set workflow result hint to be passed to converter for workflow result.
+        #
+        # @param hint [Object] Hint to set.
+        def workflow_result_hint(hint)
+          @workflow_result_hint = hint
+        end
+
         # Configure workflow failure exception types. This sets the types of exceptions that, if a
         # workflow-thrown exception extends, will cause the workflow/update to fail instead of suspending the workflow
         # via task failure. These are applied in addition to the worker option. If {::Exception} is set, it effectively
@@ -54,7 +70,7 @@ module Temporalio
         # @param types [Array<Class<Exception>>] Exception types to turn into workflow failures.
         def workflow_failure_exception_type(*types)
           types.each do |t|
-            raise ArgumentError, 'All types must classes inheriting Exception' unless t.is_a?(Class) && t < Exception
+            raise ArgumentError, 'All types must classes inheriting Exception' unless t.is_a?(Class) && t <= Exception
           end
           @workflow_failure_exception_types ||= []
           @workflow_failure_exception_types.concat(types)
@@ -71,7 +87,9 @@ module Temporalio
         # `attr_accessor`. If a writer is needed alongside this, use `attr_writer`.
         #
         # @param attr_names [Array<Symbol>] Attributes to expose.
-        def workflow_query_attr_reader(*attr_names)
+        # @param description [String, nil] Description that may appear in CLI/UI, applied to each query handler
+        #   implicitly created. This is currently experimental.
+        def workflow_query_attr_reader(*attr_names, description: nil)
           @workflow_queries ||= {}
           attr_names.each do |attr_name|
             raise 'Expected attr to be a symbol' unless attr_name.is_a?(Symbol)
@@ -83,11 +101,20 @@ module Temporalio
             end
 
             # Just run this as if done manually
-            workflow_query
+            workflow_query(description:)
             define_method(attr_name) { instance_variable_get("@#{attr_name}") }
           end
         end
 
+        # Set the versioning behavior of this workflow.
+        #
+        # WARNING: This method is experimental and may change in future versions.
+        #
+        # @param behavior [VersioningBehavior] The versioning behavior.
+        def workflow_versioning_behavior(behavior)
+          @versioning_behavior = behavior
+        end
+
         # Mark an `initialize` 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.
         #
@@ -100,6 +127,8 @@ module Temporalio
         # values.
         #
         # @param name [String, Symbol, nil] Override the default name.
+        # @param description [String, nil] Description for this handler that may appear in CLI/UI. This is currently
+        #   experimental.
         # @param dynamic [Boolean] If true, make the signal dynamic. This means it receives all other signals without
         #   handlers. This cannot have a name override since it is nameless. The first parameter will be the name. Often
         #   it is useful to have the second parameter be `*args` and `raw_args` be true.
@@ -107,40 +136,55 @@ module Temporalio
         #   {Converters::RawValue} which is a raw payload wrapper, convertible with {Workflow.payload_converter}.
         # @param unfinished_policy [HandlerUnfinishedPolicy] How to treat unfinished handlers if they are still running
         #   when the workflow ends. The default warns, but this can be disabled.
+        # @param arg_hints [Array<Object>, nil] Argument hint(s) for the signal.
         def workflow_signal(
           name: nil,
+          description: nil,
           dynamic: false,
           raw_args: false,
-          unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON
+          unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON,
+          arg_hints: nil
         )
           raise 'Cannot provide name if dynamic is true' if name && dynamic
 
-          self.pending_handler_details = { type: :signal, name:, dynamic:, raw_args:, unfinished_policy: }
+          self.pending_handler_details =
+            { type: :signal, name:, description:, dynamic:, raw_args:, unfinished_policy:,
+              arg_hints: Array(arg_hints) }
         end
 
         # Mark the next method as a workflow query with a default name as the name of the method. Queries can not have
         # any side effects, meaning they should never mutate state or try to wait on anything.
         #
         # @param name [String, Symbol, nil] Override the default name.
+        # @param description [String, nil] Description for this handler that may appear in CLI/UI. This is currently
+        #   experimental.
         # @param dynamic [Boolean] If true, make the query dynamic. This means it receives all other queries without
         #   handlers. This cannot have a name override since it is nameless. The first parameter will be the name. Often
         #   it is useful to have the second parameter be `*args` and `raw_args` be true.
         # @param raw_args [Boolean] If true, does not convert arguments, but instead provides each argument as
         #   {Converters::RawValue} which is a raw payload wrapper, convertible with {Workflow.payload_converter}.
+        # @param arg_hints [Object, Array<Object>, nil] Argument hint(s) for the query.
+        # @param result_hint [Object, nil] Result hint for the query.
         def workflow_query(
           name: nil,
+          description: nil,
           dynamic: false,
-          raw_args: false
+          raw_args: false,
+          arg_hints: nil,
+          result_hint: nil
         )
           raise 'Cannot provide name if dynamic is true' if name && dynamic
 
-          self.pending_handler_details = { type: :query, name:, dynamic:, raw_args: }
+          self.pending_handler_details = { type: :query, name:, description:, dynamic:, raw_args:,
+                                           arg_hints: Array(arg_hints), result_hint: }
         end
 
         # Mark the next method as a workflow update with a default name as the name of the method. Updates can return
         # values. Separate validation methods can be provided via {workflow_update_validator}.
         #
         # @param name [String, Symbol, nil] Override the default name.
+        # @param description [String, nil] Description for this handler that may appear in CLI/UI. This is currently
+        #   experimental.
         # @param dynamic [Boolean] If true, make the update dynamic. This means it receives all other updates without
         #   handlers. This cannot have a name override since it is nameless. The first parameter will be the name. Often
         #   it is useful to have the second parameter be `*args` and `raw_args` be true.
@@ -148,15 +192,21 @@ module Temporalio
         #   {Converters::RawValue} which is a raw payload wrapper, convertible with {Workflow.payload_converter}.
         # @param unfinished_policy [HandlerUnfinishedPolicy] How to treat unfinished handlers if they are still running
         #   when the workflow ends. The default warns, but this can be disabled.
+        # @param arg_hints [Object, Array<Object>, nil] Argument hint(s) for the update.
+        # @param result_hint [Object, nil] Result hint for the update.
         def workflow_update(
           name: nil,
+          description: nil,
           dynamic: false,
           raw_args: false,
-          unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON
+          unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON,
+          arg_hints: nil,
+          result_hint: nil
         )
           raise 'Cannot provide name if dynamic is true' if name && dynamic
 
-          self.pending_handler_details = { type: :update, name:, dynamic:, raw_args:, unfinished_policy: }
+          self.pending_handler_details = { type: :update, name:, description:, dynamic:, raw_args:, unfinished_policy:,
+                                           arg_hints: Array(arg_hints), result_hint: }
         end
 
         # Mark the next method as a workflow update validator to the given update method. The validator is expected to
@@ -169,6 +219,24 @@ module Temporalio
           self.pending_handler_details = { type: :update_validator, update_method: }
         end
 
+        # Mark the next method as returning some dynamic configuraion.
+        #
+        # Because dynamic workflows may conceptually represent more than one workflow type, it may
+        # be desirable to have different settings for fields that would normally be passed to
+        # `workflow_xxx` setters, but vary based on the workflow type name or other information
+        # available in the workflow's context. This function will be called after the workflow's
+        # `initialize`, if it has one, but before the workflow's `execute` method.
+        #
+        # The method must only take self as a parameter, and any values set in the class it returns
+        # will override those provided to other `workflow_xxx` setters.
+        #
+        # Cannot be specified on non-dynamic workflows.
+        def workflow_dynamic_options
+          raise 'Dynamic options method can only be set on workflows using `workflow_dynamic`' unless @workflow_dynamic
+
+          self.pending_handler_details = { type: :dynamic_options }
+        end
+
         private
 
         attr_reader :pending_handler_details
@@ -196,6 +264,15 @@ module Temporalio
         # Reset details
         self.pending_handler_details = nil
 
+        # Disallow kwargs in parameters
+        begin
+          if instance_method(method_name).parameters.any? { |t, _| t == :key || t == :keyreq }
+            raise "Workflow #{handler[:type]} cannot have keyword arguments"
+          end
+        rescue NameError
+          # Ignore name error
+        end
+
         # Initialize class variables if not done already
         @workflow_signals ||= {}
         @workflow_queries ||= {}
@@ -225,22 +302,35 @@ module Temporalio
             [Signal.new(
               name: handler[:dynamic] ? nil : (handler[:name] || method_name).to_s,
               to_invoke: method_name,
+              description: handler[:description],
               raw_args: handler[:raw_args],
-              unfinished_policy: handler[:unfinished_policy]
+              unfinished_policy: handler[:unfinished_policy],
+              arg_hints: handler[:arg_hints]
             ), @workflow_signals, [@workflow_queries, @workflow_updates]]
           when :query
             [Query.new(
               name: handler[:dynamic] ? nil : (handler[:name] || method_name).to_s,
               to_invoke: method_name,
-              raw_args: handler[:raw_args]
+              description: handler[:description],
+              raw_args: handler[:raw_args],
+              arg_hints: handler[:arg_hints],
+              result_hint: handler[:result_hint]
             ), @workflow_queries, [@workflow_signals, @workflow_updates]]
           when :update
             [Update.new(
               name: handler[:dynamic] ? nil : (handler[:name] || method_name).to_s,
               to_invoke: method_name,
+              description: handler[:description],
               raw_args: handler[:raw_args],
-              unfinished_policy: handler[:unfinished_policy]
+              unfinished_policy: handler[:unfinished_policy],
+              arg_hints: handler[:arg_hints],
+              result_hint: handler[:result_hint]
             ), @workflow_updates, [@workflow_signals, @workflow_queries]]
+          when :dynamic_options
+            raise 'Dynamic options method already set' if @dynamic_options_method
+
+            @dynamic_options_method = method_name
+            return
           else
             raise "Unrecognized handler type #{handler[:type]}"
           end
@@ -278,7 +368,7 @@ module Temporalio
       end
 
       # @!visibility private
-      def self._workflow_type_from_workflow_parameter(workflow)
+      def self._workflow_type_and_hints_from_workflow_parameter(workflow)
         case workflow
         when Class
           unless workflow < Definition
@@ -286,11 +376,15 @@ module Temporalio
           end
 
           info = Info.from_class(workflow)
-          info.name || raise(ArgumentError, 'Cannot pass dynamic workflow to start')
+          raise(ArgumentError, 'Cannot pass dynamic workflow to start') unless info.name
+
+          [info.name.to_s, info.arg_hints, info.result_hint]
         when Info
-          workflow.name || raise(ArgumentError, 'Cannot pass dynamic workflow to start')
+          raise(ArgumentError, 'Cannot pass dynamic workflow to start') unless workflow.name
+
+          [workflow.name.to_s, nil, nil]
         when String, Symbol
-          workflow.to_s
+          [workflow.to_s, nil, nil]
         else
           raise ArgumentError, 'Workflow is not a workflow class or string/symbol'
         end
@@ -303,6 +397,11 @@ module Temporalio
           raise "Leftover #{pending_handler_details&.[](:type)} handler not applied to a method"
         end
 
+        # Disallow kwargs in execute parameters
+        if instance_method(:execute).parameters.any? { |t, _| t == :key || t == :keyreq }
+          raise 'Workflow execute cannot have keyword arguments'
+        end
+
         # Apply all update validators before merging with super
         updates = @workflow_updates&.dup || {}
         @workflow_update_validators&.each_value do |validator|
@@ -372,6 +471,10 @@ module Temporalio
 
         raise 'Workflow cannot be given a name and be dynamic' if dynamic && override_name
 
+        if !dynamic && !@dynamic_options_method.nil?
+          raise 'Workflow cannot have a dynamic_options_method unless it is dynamic'
+        end
+
         Info.new(
           workflow_class: self,
           override_name:,
@@ -381,7 +484,11 @@ module Temporalio
           failure_exception_types: @workflow_failure_exception_types || [],
           signals:,
           queries:,
-          updates:
+          updates:,
+          versioning_behavior: @versioning_behavior || VersioningBehavior::UNSPECIFIED,
+          dynamic_options_method: @dynamic_options_method,
+          arg_hints: @workflow_arg_hints,
+          result_hint: @workflow_result_hint
         )
       end
 
@@ -394,7 +501,8 @@ module Temporalio
       # Information about the workflow definition. This is usually not used directly.
       class Info
         attr_reader :workflow_class, :override_name, :dynamic, :init, :raw_args,
-                    :failure_exception_types, :signals, :queries, :updates
+                    :failure_exception_types, :signals, :queries, :updates, :versioning_behavior,
+                    :dynamic_options_method, :arg_hints, :result_hint
 
         # Derive the workflow definition info from the class.
         #
@@ -419,7 +527,11 @@ module Temporalio
           failure_exception_types: [],
           signals: {},
           queries: {},
-          updates: {}
+          updates: {},
+          versioning_behavior: VersioningBehavior::UNSPECIFIED,
+          dynamic_options_method: nil,
+          arg_hints: nil,
+          result_hint: nil
         )
           @workflow_class = workflow_class
           @override_name = override_name
@@ -430,6 +542,11 @@ module Temporalio
           @signals = signals.dup.freeze
           @queries = queries.dup.freeze
           @updates = updates.dup.freeze
+          @versioning_behavior = versioning_behavior
+          @dynamic_options_method = dynamic_options_method
+          @arg_hints = arg_hints
+          @result_hint = result_hint
+          Internal::ProtoUtils.assert_non_reserved_name(name)
         end
 
         # @return [String] Workflow name.
@@ -441,15 +558,17 @@ module Temporalio
       # A signal definition. This is usually built as a result of a {Definition.workflow_signal} method, but can be
       # manually created to set at runtime on {Workflow.signal_handlers}.
       class Signal
-        attr_reader :name, :to_invoke, :raw_args, :unfinished_policy
+        attr_reader :name, :to_invoke, :description, :raw_args, :unfinished_policy, :arg_hints
 
         # @!visibility private
-        def self._name_from_parameter(signal)
+        def self._name_and_hints_from_parameter(signal)
           case signal
           when Workflow::Definition::Signal
-            signal.name || raise(ArgumentError, 'Cannot call dynamic signal directly')
+            raise(ArgumentError, 'Cannot call dynamic signal directly') unless signal.name
+
+            [signal.name, signal.arg_hints]
           when String, Symbol
-            signal.to_s
+            [signal.to_s, nil]
           else
             raise ArgumentError, 'Signal is not a definition or string/symbol'
           end
@@ -460,34 +579,44 @@ module Temporalio
         #
         # @param name [String, nil] Name or nil if dynamic.
         # @param to_invoke [Symbol, Proc] Method name or proc to invoke.
+        # @param description [String, nil] Description for this handler that may appear in CLI/UI. This is currently
+        #   experimental.
         # @param raw_args [Boolean] Whether the parameters should be raw values.
         # @param unfinished_policy [HandlerUnfinishedPolicy] How the workflow reacts when this handler is still running
         #   on workflow completion.
+        # @param arg_hints [Array<Object>, nil] Argument hints for the signal.
         def initialize(
           name:,
           to_invoke:,
+          description: nil,
           raw_args: false,
-          unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON
+          unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON,
+          arg_hints: nil
         )
           @name = name
           @to_invoke = to_invoke
+          @description = description
           @raw_args = raw_args
           @unfinished_policy = unfinished_policy
+          @arg_hints = arg_hints
+          Internal::ProtoUtils.assert_non_reserved_name(name)
         end
       end
 
       # A query definition. This is usually built as a result of a {Definition.workflow_query} method, but can be
       # manually created to set at runtime on {Workflow.query_handlers}.
       class Query
-        attr_reader :name, :to_invoke, :raw_args
+        attr_reader :name, :to_invoke, :description, :raw_args, :arg_hints, :result_hint
 
         # @!visibility private
-        def self._name_from_parameter(query)
+        def self._name_and_hints_from_parameter(query)
           case query
           when Workflow::Definition::Query
-            query.name || raise(ArgumentError, 'Cannot call dynamic query directly')
+            raise(ArgumentError, 'Cannot call dynamic query directly') unless query.name
+
+            [query.name, query.arg_hints, query.result_hint]
           when String, Symbol
-            query.to_s
+            [query.to_s, nil, nil]
           else
             raise ArgumentError, 'Query is not a definition or string/symbol'
           end
@@ -498,30 +627,44 @@ module Temporalio
         #
         # @param name [String, nil] Name or nil if dynamic.
         # @param to_invoke [Symbol, Proc] Method name or proc to invoke.
+        # @param description [String, nil] Description for this handler that may appear in CLI/UI. This is currently
+        #   experimental.
         # @param raw_args [Boolean] Whether the parameters should be raw values.
+        # @param arg_hints [Array<Object>, nil] Argument hints for the query.
+        # @param result_hint [Object, nil] Result hints for the query.
         def initialize(
           name:,
           to_invoke:,
-          raw_args: false
+          description: nil,
+          raw_args: false,
+          arg_hints: nil,
+          result_hint: nil
         )
           @name = name
           @to_invoke = to_invoke
+          @description = description
           @raw_args = raw_args
+          @arg_hints = arg_hints
+          @result_hint = result_hint
+          Internal::ProtoUtils.assert_non_reserved_name(name)
         end
       end
 
       # An update definition. This is usually built as a result of a {Definition.workflow_update} method, but can be
       # manually created to set at runtime on {Workflow.update_handlers}.
       class Update
-        attr_reader :name, :to_invoke, :raw_args, :unfinished_policy, :validator_to_invoke
+        attr_reader :name, :to_invoke, :description, :raw_args, :unfinished_policy, :validator_to_invoke,
+                    :arg_hints, :result_hint
 
         # @!visibility private
-        def self._name_from_parameter(update)
+        def self._name_and_hints_from_parameter(update)
           case update
           when Workflow::Definition::Update
-            update.name || raise(ArgumentError, 'Cannot call dynamic update directly')
+            raise(ArgumentError, 'Cannot call dynamic update directly') unless update.name
+
+            [update.name, update.arg_hints, update.result_hint]
           when String, Symbol
-            update.to_s
+            [update.to_s, nil, nil]
           else
             raise ArgumentError, 'Update is not a definition or string/symbol'
           end
@@ -532,22 +675,33 @@ module Temporalio
         #
         # @param name [String, nil] Name or nil if dynamic.
         # @param to_invoke [Symbol, Proc] Method name or proc to invoke.
+        # @param description [String, nil] Description for this handler that may appear in CLI/UI. This is currently
+        #   experimental.
         # @param raw_args [Boolean] Whether the parameters should be raw values.
         # @param unfinished_policy [HandlerUnfinishedPolicy] How the workflow reacts when this handler is still running
         #   on workflow completion.
         # @param validator_to_invoke [Symbol, Proc, nil] Method name or proc validator to invoke.
+        # @param arg_hints [Array<Object>, nil] Argument hints for the update.
+        # @param result_hint [Object, nil] Result hints for the update.
         def initialize(
           name:,
           to_invoke:,
+          description: nil,
           raw_args: false,
           unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON,
-          validator_to_invoke: nil
+          validator_to_invoke: nil,
+          arg_hints: nil,
+          result_hint: nil
         )
           @name = name
           @to_invoke = to_invoke
+          @description = description
           @raw_args = raw_args
           @unfinished_policy = unfinished_policy
           @validator_to_invoke = validator_to_invoke
+          @arg_hints = arg_hints
+          @result_hint = result_hint
+          Internal::ProtoUtils.assert_non_reserved_name(name)
         end
 
         # @!visibility private
@@ -555,12 +709,40 @@ module Temporalio
           Update.new(
             name:,
             to_invoke:,
+            description:,
             raw_args:,
             unfinished_policy:,
-            validator_to_invoke:
+            validator_to_invoke:,
+            arg_hints:,
+            result_hint:
           )
         end
       end
     end
+
+    DefinitionOptions = Struct.new(
+      :failure_exception_types,
+      :versioning_behavior
+    )
+    # @!attribute failure_exception_types
+    #   Dynamic equivalent of {Definition.workflow_failure_exception_type}.
+    #   Will override any types set there if set, including if set to an empty array.
+    #   @return [Array<Class<Exception>>, nil] The failure exception types
+    #
+    # @!attribute versioning_behavior
+    #   Dynamic equivalent of {Definition.workflow_versioning_behavior}.
+    #   Will override any behavior set there if set.
+    #   WARNING: Deployment-based versioning is experimental and APIs may change.
+    #   @return [VersioningBehavior, nil] The versioning behavior
+    #
+    # @return [VersioningBehavior, nil] The versioning behavior
+    class DefinitionOptions
+      def initialize(
+        failure_exception_types: nil,
+        versioning_behavior: nil
+      )
+        super
+      end
+    end
   end
 end

data/lib/temporalio/workflow/external_workflow_handle.rb

@@ -28,7 +28,9 @@ module Temporalio
       # @param signal [Workflow::Definition::Signal, Symbol, String] Signal definition or name.
       # @param args [Array<Object>] Signal args.
       # @param cancellation [Cancellation] Cancellation for canceling the signalling.
-      def signal(signal, *args, cancellation: Workflow.cancellation)
+      # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+      #   signal definition has arg hints, those are used by default.
+      def signal(signal, *args, cancellation: Workflow.cancellation, arg_hints: nil)
         raise NotImplementedError
       end
 

data/lib/temporalio/workflow/future.rb

@@ -8,7 +8,7 @@ module Temporalio
     # workflows.
     class Future
       # Return a future that completes when any of the given futures complete. The returned future will return the first
-      # completed futures value or raise the first completed futures exception. To not raise the exception, see
+      # completed future's value or raise the first completed future's exception. To not raise the exception, see
       # {try_any_of}.
       #
       # @param futures [Array<Future<Object>>] Futures to wait for the first to complete.
@@ -16,7 +16,7 @@ module Temporalio
       def self.any_of(*futures)
         Future.new do
           Workflow.wait_condition(cancellation: nil) { futures.any?(&:done?) }
-          # We know a future is always returned from find, the & just helps type checker
+          # We know a future is always returned from find, the || just helps type checker
           (futures.find(&:done?) || raise).wait
         end
       end

data/lib/temporalio/workflow/info.rb

@@ -7,11 +7,14 @@ module Temporalio
       :continued_run_id,
       :cron_schedule,
       :execution_timeout,
+      :headers,
       :last_failure,
       :last_result,
       :namespace,
       :parent,
+      :priority,
       :retry_policy,
+      :root,
       :run_id,
       :run_timeout,
       :start_time,
@@ -32,6 +35,8 @@ module Temporalio
     #   @return [String, nil] Cron schedule if applicable.
     # @!attribute execution_timeout
     #   @return [Float, nil] Execution timeout for the workflow.
+    # @!attribute headers
+    #   @return [Hash<String, Api::Common::V1::Payload>] Headers.
     # @!attribute last_failure
     #   @return [Exception, nil] Failure if this workflow run is a continuation of a failure.
     # @!attribute last_result
@@ -40,14 +45,19 @@ module Temporalio
     #   @return [String] Namespace for the workflow.
     # @!attribute parent
     #   @return [ParentInfo, nil] Parent information for the workflow if this is a child.
+    # @!attribute priority
+    #   @return [Priority] The priority of this workflow.
     # @!attribute retry_policy
     #   @return [RetryPolicy, nil] Retry policy for the workflow.
+    # @!attribute root
+    #   @return [RootInfo, nil] Root information for the workflow. This is nil in pre-1.27.0 server versions or if there
+    #     is no root (i.e. the root is itself).
     # @!attribute run_id
     #   @return [String] Run ID for the workflow.
     # @!attribute run_timeout
     #   @return [Float, nil] Run timeout for the workflow.
     # @!attribute start_time
-    #   @return [Time] Time when the workflow started.
+    #   @return [Time] Time when the workflow started on the server.
     # @!attribute task_queue
     #   @return [String] Task queue for the workflow.
     # @!attribute task_timeout
@@ -77,6 +87,21 @@ module Temporalio
         :workflow_id,
         keyword_init: true
       )
+
+      # Information about a root of a workflow.
+      #
+      # @!attribute run_id
+      #   @return [String] Run ID for the root.
+      # @!attribute workflow_id
+      #   @return [String] Workflow ID for the root.
+      #
+      # @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.
+      RootInfo = Struct.new(
+        :run_id,
+        :workflow_id,
+        keyword_init: true
+      )
     end
   end
 end