temporalio 0.3.0 → 0.5.0

data/lib/temporalio/client/schedule.rb

@@ -167,12 +167,15 @@ module Temporalio
           :args,
           :id,
           :task_queue,
+          :static_summary,
+          :static_details,
           :execution_timeout,
           :run_timeout,
           :task_timeout,
           :retry_policy,
           :memo,
           :search_attributes,
+          :arg_hints,
           :headers
         )
 
@@ -186,6 +189,14 @@ module Temporalio
         #   @return [String] Unique identifier for the workflow execution.
         # @!attribute task_queue
         #   @return [String] Task queue to run the workflow on.
+        # @!attribute static_summary
+        #   @return [String, nil] Fixed single-line summary for this workflow execution that may appear in CLI/UI.
+        #     This can be in single-line Temporal markdown format. This is currently experimental.
+        # @!attribute static_details
+        #   @return [String, nil] Fixed details for this workflow execution that may appear in CLI/UI. This can be in
+        #     Temporal markdown format and can be multiple lines. This is a fixed value on the workflow that cannot be
+        #     updated. For details that can be updated, use {Workflow.current_details=} within the workflow. This is
+        #     currently experimental.
         # @!attribute execution_timeout
         #   @return [Float, nil] Total workflow execution timeout in seconds including retries and continue as new.
         # @!attribute run_timeout
@@ -198,6 +209,9 @@ module Temporalio
         #   @return [Hash<String, Object>, nil] Memo for the workflow.
         # @!attribute search_attributes
         #   @return [SearchAttributes, nil] Search attributes for the workflow.
+        # @!attribute arg_hints
+        #   @return [Array<Object>, nil] Converter hints for workflow arguments. This is only user-set (e.g. on create)
+        #     and is not persisted and therefore will not be set when describing a workflow.
         # @!attribute headers
         #   @return [Hash<String, Object>, nil] Headers for the workflow.
         class StartWorkflow
@@ -212,6 +226,12 @@ module Temporalio
             # @param args [Array<Object>] Arguments to the workflow.
             # @param id [String] Unique identifier for the workflow execution.
             # @param task_queue [String] Task queue to run the workflow on.
+            # @param static_summary [String, nil] Fixed single-line summary for this workflow execution that may appear
+            #   in CLI/UI. This can be in single-line Temporal markdown format. This is currently experimental.
+            # @param static_details [String, nil] Fixed details for this workflow execution that may appear in CLI/UI.
+            #   This can be in Temporal markdown format and can be multiple lines. This is a fixed value on the workflow
+            #   that cannot be updated. For details that can be updated, use {Workflow.current_details=} within the
+            #   workflow. This is currently experimental.
             # @param execution_timeout [Float, nil] Total workflow execution timeout in seconds including retries and
             #   continue as new.
             # @param run_timeout [Float, nil] Timeout of a single workflow run in seconds.
@@ -225,25 +245,33 @@ module Temporalio
               *args,
               id:,
               task_queue:,
+              static_summary: nil,
+              static_details: nil,
               execution_timeout: nil,
               run_timeout: nil,
               task_timeout: nil,
               retry_policy: nil,
               memo: nil,
               search_attributes: nil,
+              arg_hints: nil,
               headers: nil
             )
+              workflow, defn_arg_hints, =
+                Workflow::Definition._workflow_type_and_hints_from_workflow_parameter(workflow)
               _original_new( # steep:ignore
-                workflow: Workflow::Definition._workflow_type_from_workflow_parameter(workflow),
+                workflow:,
                 args:,
                 id:,
                 task_queue:,
+                static_summary:,
+                static_details:,
                 execution_timeout:,
                 run_timeout:,
                 task_timeout:,
                 retry_policy:,
                 memo:,
                 search_attributes:,
+                arg_hints: arg_hints || defn_arg_hints,
                 headers:
               )
             end
@@ -251,11 +279,14 @@ module Temporalio
 
           # @!visibility private
           def self._from_proto(raw_info, data_converter)
+            (summary, details) = Internal::ProtoUtils.from_user_metadata(raw_info.user_metadata, data_converter)
             StartWorkflow.new(
               raw_info.workflow_type.name,
               *data_converter.from_payloads(raw_info.input),
               id: raw_info.workflow_id,
               task_queue: raw_info.task_queue.name,
+              static_summary: summary,
+              static_details: details,
               execution_timeout: Internal::ProtoUtils.duration_to_seconds(raw_info.workflow_execution_timeout),
               run_timeout: Internal::ProtoUtils.duration_to_seconds(raw_info.workflow_run_timeout),
               task_timeout: Internal::ProtoUtils.duration_to_seconds(raw_info.workflow_task_timeout),
@@ -273,14 +304,15 @@ module Temporalio
                 workflow_id: id,
                 workflow_type: Api::Common::V1::WorkflowType.new(name: workflow),
                 task_queue: Api::TaskQueue::V1::TaskQueue.new(name: task_queue),
-                input: data_converter.to_payloads(args),
+                input: data_converter.to_payloads(args, hints: arg_hints),
                 workflow_execution_timeout: Internal::ProtoUtils.seconds_to_duration(execution_timeout),
                 workflow_run_timeout: Internal::ProtoUtils.seconds_to_duration(run_timeout),
                 workflow_task_timeout: Internal::ProtoUtils.seconds_to_duration(task_timeout),
                 retry_policy: retry_policy&._to_proto,
                 memo: Internal::ProtoUtils.memo_to_proto(memo, data_converter),
                 search_attributes: search_attributes&._to_proto,
-                header: Internal::ProtoUtils.headers_to_proto(headers, data_converter)
+                header: Internal::ProtoUtils.headers_to_proto(headers, data_converter),
+                user_metadata: Internal::ProtoUtils.to_user_metadata(static_summary, static_details, data_converter)
               )
             )
           end

data/lib/temporalio/client/with_start_workflow_operation.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'temporalio/common_enums'
+
+module Temporalio
+  class Client
+    # Start operation used by {Client.start_update_with_start_workflow}, {Client.execute_update_with_start_workflow},
+    # and {Client.signal_with_start_workflow}.
+    class WithStartWorkflowOperation
+      Options = Data.define(
+        :workflow,
+        :args,
+        :id,
+        :task_queue,
+        :static_summary,
+        :static_details,
+        :execution_timeout,
+        :run_timeout,
+        :task_timeout,
+        :id_reuse_policy,
+        :id_conflict_policy,
+        :retry_policy,
+        :cron_schedule,
+        :memo,
+        :search_attributes,
+        :start_delay,
+        :arg_hints,
+        :result_hint,
+        :headers
+      )
+
+      # Options the operation was created with.
+      class Options; end # rubocop:disable Lint/EmptyClass
+
+      # @return [Options] Options the operation was created with.
+      attr_accessor :options
+
+      # Create a with-start workflow operation. These are mostly the same options as {Client.start_workflow}, see that
+      # documentation for more details.
+      #
+      # Note, for {Client.start_update_with_start_workflow} and {Client.execute_update_with_start_workflow},
+      # `id_conflict_policy` is required.
+      def initialize(
+        workflow,
+        *args,
+        id:,
+        task_queue:,
+        static_summary: nil,
+        static_details: nil,
+        execution_timeout: nil,
+        run_timeout: nil,
+        task_timeout: nil,
+        id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE,
+        id_conflict_policy: WorkflowIDConflictPolicy::UNSPECIFIED,
+        retry_policy: nil,
+        cron_schedule: nil,
+        memo: nil,
+        search_attributes: nil,
+        start_delay: nil,
+        arg_hints: nil,
+        result_hint: nil,
+        headers: {}
+      )
+        workflow, defn_arg_hints, defn_result_hint =
+          Workflow::Definition._workflow_type_and_hints_from_workflow_parameter(workflow)
+        @options = Options.new(
+          workflow:,
+          args:,
+          id:,
+          task_queue:,
+          static_summary:,
+          static_details:,
+          execution_timeout:,
+          run_timeout:,
+          task_timeout:,
+          id_reuse_policy:,
+          id_conflict_policy:,
+          retry_policy:,
+          cron_schedule:,
+          memo:,
+          search_attributes:,
+          start_delay:,
+          arg_hints: arg_hints || defn_arg_hints,
+          result_hint: result_hint || defn_result_hint,
+          headers:
+        )
+        @workflow_handle_mutex = Mutex.new
+        @workflow_handle_cond_var = ConditionVariable.new
+      end
+
+      # Get the workflow handle, possibly waiting until set, or raise an error if the workflow start was unsuccessful.
+      #
+      # @param wait [Boolean] True to wait until it is set, false to return immediately.
+      #
+      # @return [WorkflowHandle, nil] The workflow handle when available or `nil` if `wait` is false and it is not set
+      #   yet.
+      # @raise [Error] Any error that occurred during the call before the workflow start returned.
+      def workflow_handle(wait: true)
+        @workflow_handle_mutex.synchronize do
+          @workflow_handle_cond_var.wait(@workflow_handle_mutex) unless @workflow_handle || !wait
+          raise @workflow_handle if @workflow_handle.is_a?(Exception)
+
+          @workflow_handle
+        end
+      end
+
+      # @!visibility private
+      def _set_workflow_handle(value)
+        @workflow_handle_mutex.synchronize do
+          @workflow_handle ||= value
+          @workflow_handle_cond_var.broadcast
+        end
+      end
+
+      # @!visibility private
+      def _mark_used
+        raise 'Start operation already used' if @in_use
+
+        @in_use = true
+      end
+    end
+  end
+end

data/lib/temporalio/client/workflow_execution.rb

@@ -93,6 +93,25 @@ module Temporalio
         def initialize(raw_description, data_converter)
           super(raw_description.workflow_execution_info, data_converter)
           @raw_description = raw_description
+          @data_converter = data_converter
+        end
+
+        # @return [String, nil] Static summary configured on the workflow. This is currently experimental.
+        def static_summary
+          user_metadata.first
+        end
+
+        # @return [String, nil] Static details configured on the workflow. This is currently experimental.
+        def static_details
+          user_metadata.last
+        end
+
+        private
+
+        def user_metadata
+          @user_metadata ||= Internal::ProtoUtils.from_user_metadata(
+            @raw_description.execution_config&.user_metadata, @data_converter
+          )
         end
       end
     end

data/lib/temporalio/client/workflow_handle.rb

@@ -48,13 +48,21 @@ module Temporalio
       # @return [String, nil] First execution run ID.
       attr_reader :first_execution_run_id
 
+      # Result hint for the result of this workflow. If this handle was created via {Client.start_workflow}, this is set
+      # from there (either via result hint on that call or workflow definition's result hint). Otherwise, the result
+      # hint is set by the creator of the handle.
+      #
+      # @return [Object, nil] Result hint.
+      attr_reader :result_hint
+
       # @!visibility private
-      def initialize(client:, id:, run_id:, result_run_id:, first_execution_run_id:)
+      def initialize(client:, id:, run_id:, result_run_id:, first_execution_run_id:, result_hint:)
         @client = client
         @id = id
         @run_id = run_id
         @result_run_id = result_run_id
         @first_execution_run_id = first_execution_run_id
+        @result_hint = result_hint
       end
 
       # Wait for the result of the workflow.
@@ -64,6 +72,8 @@ module Temporalio
       #
       # @param follow_runs [Boolean] If +true+, workflow runs will be continually fetched across retries and continue as
       #   new until the latest one is found. If +false+, the first result is used.
+      # @param result_hint [Object, nil] Override the result hint for the result. If unset/nil, uses one on the handle
+      #   itself.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object] Result of the workflow after being converted by the data converter.
@@ -71,7 +81,7 @@ module Temporalio
       # @raise [Error::WorkflowFailedError] Workflow failed with +cause+ as the cause.
       # @raise [Error::WorkflowContinuedAsNewError] Workflow continued as new and +follow_runs+ is +false+.
       # @raise [Error::RPCError] RPC error from call.
-      def result(follow_runs: true, rpc_options: nil)
+      def result(follow_runs: true, result_hint: nil, rpc_options: nil)
         # Wait on the close event, following as needed
         hist_run_id = result_run_id
         loop do
@@ -91,7 +101,7 @@ module Temporalio
             hist_run_id = attrs.new_execution_run_id
             next if follow_runs && hist_run_id && !hist_run_id.empty?
 
-            return @client.data_converter.from_payloads(attrs.result).first
+            return @client.data_converter.from_payloads(attrs.result, hints: Array(@result_hint || result_hint)).first
           when :EVENT_TYPE_WORKFLOW_EXECUTION_FAILED
             attrs = event.workflow_execution_failed_event_attributes
             hist_run_id = attrs.new_execution_run_id
@@ -212,18 +222,22 @@ module Temporalio
       #
       # @param signal [Workflow::Definition::Signal, Symbol, String] Signal definition or name.
       # @param args [Array<Object>] Signal arguments.
+      # @param arg_hints [Array<Object>, nil] Signal argument hints. If unset/nil and a signal definition is passed,
+      #   uses the ones on the signal definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @raise [Error::RPCError] RPC error from call.
       #
       # @note Handles created as a result of {Client.start_workflow} will signal the latest workflow with the same
       #   workflow ID even if it is unrelated to the started workflow.
-      def signal(signal, *args, rpc_options: nil)
+      def signal(signal, *args, arg_hints: nil, rpc_options: nil)
+        signal, defn_arg_hints = Workflow::Definition::Signal._name_and_hints_from_parameter(signal)
         @client._impl.signal_workflow(Interceptor::SignalWorkflowInput.new(
                                         workflow_id: id,
                                         run_id:,
                                         signal:,
                                         args:,
+                                        arg_hints: arg_hints || defn_arg_hints,
                                         headers: {},
                                         rpc_options:
                                       ))
@@ -235,6 +249,10 @@ module Temporalio
       # @param query [Workflow::Definition::Query, Symbol, String] Query definition or name.
       # @param args [Array<Object>] Query arguments.
       # @param reject_condition [WorkflowQueryRejectCondition, nil] Condition for rejecting the query.
+      # @param arg_hints [Array<Object>, nil] Query argument hints. If unset/nil and a query definition is passed,
+      #   uses the ones on the query definition if present.
+      # @param result_hint [Object, nil] Query result hints. If unset/nil and a query definition is passed, uses the
+      #   one on the query definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Query result.
@@ -249,14 +267,19 @@ module Temporalio
         query,
         *args,
         reject_condition: @client.options.default_workflow_query_reject_condition,
+        arg_hints: nil,
+        result_hint: nil,
         rpc_options: nil
       )
+        query, defn_arg_hints, defn_result_hint = Workflow::Definition::Query._name_and_hints_from_parameter(query)
         @client._impl.query_workflow(Interceptor::QueryWorkflowInput.new(
                                        workflow_id: id,
                                        run_id:,
                                        query:,
                                        args:,
                                        reject_condition:,
+                                       arg_hints: arg_hints || defn_arg_hints,
+                                       result_hint: result_hint || defn_result_hint,
                                        headers: {},
                                        rpc_options:
                                      ))
@@ -270,6 +293,10 @@ module Temporalio
       # @param wait_for_stage [WorkflowUpdateWaitStage] Required stage to wait until returning. ADMITTED is not
       #   currently supported. See https://docs.temporal.io/workflows#update for more details.
       # @param id [String] ID of the update.
+      # @param arg_hints [Array<Object>, nil] Update argument hints. If unset/nil and am update definition is passed,
+      #   uses the ones on the update definition if present.
+      # @param result_hint [Object, nil] Update result hints. If unset/nil and an update definition is passed, uses the
+      #   one on the update definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [WorkflowUpdateHandle] The update handle.
@@ -285,8 +312,11 @@ module Temporalio
         *args,
         wait_for_stage:,
         id: SecureRandom.uuid,
+        arg_hints: nil,
+        result_hint: nil,
         rpc_options: nil
       )
+        update, defn_arg_hints, defn_result_hint = Workflow::Definition::Update._name_and_hints_from_parameter(update)
         @client._impl.start_workflow_update(Interceptor::StartWorkflowUpdateInput.new(
                                               workflow_id: self.id,
                                               run_id:,
@@ -294,6 +324,8 @@ module Temporalio
                                               update:,
                                               args:,
                                               wait_for_stage:,
+                                              arg_hints: arg_hints || defn_arg_hints,
+                                              result_hint: result_hint || defn_result_hint,
                                               headers: {},
                                               rpc_options:
                                             ))
@@ -305,6 +337,10 @@ module Temporalio
       # @param update [Workflow::Definition::Update, Symbol, String] Update definition or name.
       # @param args [Array<Object>] Update arguments.
       # @param id [String] ID of the update.
+      # @param arg_hints [Array<Object>, nil] Update argument hints. If unset/nil and am update definition is passed,
+      #   uses the ones on the update definition if present.
+      # @param result_hint [Object, nil] Update result hints. If unset/nil and an update definition is passed, uses the
+      #   one on the update definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Update result.
@@ -316,12 +352,14 @@ module Temporalio
       #
       # @note Handles created as a result of {Client.start_workflow} will send updates the latest workflow with the same
       #   workflow ID even if it is unrelated to the started workflow.
-      def execute_update(update, *args, id: SecureRandom.uuid, rpc_options: nil)
+      def execute_update(update, *args, id: SecureRandom.uuid, arg_hints: nil, result_hint: nil, rpc_options: nil)
         start_update(
           update,
           *args,
           wait_for_stage: WorkflowUpdateWaitStage::COMPLETED,
           id:,
+          arg_hints:,
+          result_hint:,
           rpc_options:
         ).result
       end
@@ -331,15 +369,17 @@ module Temporalio
       # @param id [String] ID of the update.
       # @param specific_run_id [String, nil] Workflow run ID to get update handle for. Default is the {run_id}. Most
       #   users will not need to set this and instead use the one on the class.
+      # @param result_hint [Object, nil] Result hint for the update result to set on the handle.
       #
       # @return [WorkflowUpdateHandle] The update handle.
-      def update_handle(id, specific_run_id: run_id)
+      def update_handle(id, specific_run_id: run_id, result_hint: nil)
         WorkflowUpdateHandle.new(
           client: @client,
           id:,
           workflow_id: self.id,
           workflow_run_id: specific_run_id,
-          known_outcome: nil
+          known_outcome: nil,
+          result_hint:
         )
       end
 

data/lib/temporalio/client/workflow_update_handle.rb

@@ -18,13 +18,17 @@ module Temporalio
       # @return [String, nil] Run ID for the workflow.
       attr_reader :workflow_run_id
 
+      # @return [Object, nil] Result hint if one set when the handle was created.
+      attr_reader :result_hint
+
       # @!visibility private
-      def initialize(client:, id:, workflow_id:, workflow_run_id:, known_outcome:)
+      def initialize(client:, id:, workflow_id:, workflow_run_id:, known_outcome:, result_hint:)
         @client = client
         @id = id
         @workflow_id = workflow_id
         @workflow_run_id = workflow_run_id
         @known_outcome = known_outcome
+        @result_hint = result_hint
       end
 
       # @return [Boolean] True if the result is already known and {result} will not make a blocking call, false if
@@ -36,6 +40,7 @@ module Temporalio
       # Wait for and return the result of the update. The result may already be known in which case no network call is
       # made. Otherwise the result will be polled for until it is returned.
       #
+      # @param result_hint [Object, nil] If not nil, overrides handle-level result hint for getting the result.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Update result.
@@ -44,7 +49,7 @@ module Temporalio
       # @raise [Error::WorkflowUpdateRPCTimeoutOrCanceledError] This update call timed out or was canceled. This doesn't
       #   mean the update itself was timed out or canceled.
       # @raise [Error::RPCError] RPC error from call.
-      def result(rpc_options: nil)
+      def result(result_hint: nil, rpc_options: nil)
         @known_outcome ||= @client._impl.poll_workflow_update(Interceptor::PollWorkflowUpdateInput.new(
                                                                 workflow_id:,
                                                                 run_id: workflow_run_id,
@@ -56,7 +61,8 @@ module Temporalio
           raise Error::WorkflowUpdateFailedError.new, cause: @client.data_converter.from_failure(@known_outcome.failure)
         end
 
-        results = @client.data_converter.from_payloads(@known_outcome.success)
+        results = @client.data_converter.from_payloads(@known_outcome.success,
+                                                       hints: Array(result_hint || @result_hint))
         warn("Expected 0 or 1 update result, got #{results.size}") if results.size > 1
         results.first
       end