temporalio 0.4.0-x86_64-linux-musl → 0.6.0-x86_64-linux-musl

data/lib/temporalio/workflow/definition.rb

@@ -47,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
@@ -55,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)
@@ -91,6 +106,15 @@ module Temporalio
           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.
         #
@@ -112,16 +136,20 @@ 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:, description:, 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
@@ -135,15 +163,20 @@ module Temporalio
         #   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:, description:, 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
@@ -159,16 +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:, description:, 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
@@ -181,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
@@ -208,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 ||= {}
@@ -215,7 +280,7 @@ module Temporalio
         @workflow_update_validators ||= {}
         @defined_methods ||= []
 
-        defn, hash, other_hashes =
+        defn, hash =
           case handler[:type]
           when :init
             raise "workflow_init was applied to #{method_name} instead of initialize" if method_name != :initialize
@@ -239,23 +304,33 @@ module Temporalio
               to_invoke: method_name,
               description: handler[:description],
               raw_args: handler[:raw_args],
-              unfinished_policy: handler[:unfinished_policy]
-            ), @workflow_signals, [@workflow_queries, @workflow_updates]]
+              unfinished_policy: handler[:unfinished_policy],
+              arg_hints: handler[:arg_hints]
+            ), @workflow_signals]
           when :query
             [Query.new(
               name: handler[:dynamic] ? nil : (handler[:name] || method_name).to_s,
               to_invoke: method_name,
               description: handler[:description],
-              raw_args: handler[:raw_args]
-            ), @workflow_queries, [@workflow_signals, @workflow_updates]]
+              raw_args: handler[:raw_args],
+              arg_hints: handler[:arg_hints],
+              result_hint: handler[:result_hint]
+            ), @workflow_queries]
           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]
-            ), @workflow_updates, [@workflow_signals, @workflow_queries]]
+              unfinished_policy: handler[:unfinished_policy],
+              arg_hints: handler[:arg_hints],
+              result_hint: handler[:result_hint]
+            ), @workflow_updates]
+          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
@@ -266,8 +341,6 @@ module Temporalio
         if other && other.to_invoke != method_name
           raise "Workflow #{handler[:type].name} #{defn.name || '<dynamic>'} defined on " \
                 "different methods #{other.to_invoke} and #{method_name}"
-        elsif defn.name && other_hashes.any? { |h| h.include?(defn.name) }
-          raise "Workflow signal #{defn.name} already defined as a different handler type"
         end
         hash[defn.name] = defn
 
@@ -293,7 +366,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
@@ -301,11 +374,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
@@ -318,6 +395,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|
@@ -387,6 +469,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:,
@@ -396,7 +482,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
 
@@ -409,7 +499,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.
         #
@@ -434,7 +525,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
@@ -445,6 +540,10 @@ 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
 
@@ -457,15 +556,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, :description, :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
@@ -481,18 +582,21 @@ module Temporalio
         # @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
@@ -500,15 +604,17 @@ module Temporalio
       # 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, :description, :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
@@ -522,16 +628,22 @@ module Temporalio
         # @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:,
           description: nil,
-          raw_args: false
+          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
@@ -539,15 +651,18 @@ module Temporalio
       # 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, :description, :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
@@ -564,13 +679,17 @@ module Temporalio
         # @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
@@ -578,6 +697,8 @@ module Temporalio
           @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
 
@@ -589,10 +710,37 @@ module Temporalio
             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/info.rb

@@ -12,6 +12,7 @@ module Temporalio
       :last_result,
       :namespace,
       :parent,
+      :priority,
       :retry_policy,
       :root,
       :run_id,
@@ -44,6 +45,8 @@ 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
@@ -54,7 +57,7 @@ module Temporalio
     # @!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