temporalio 0.2.0 → 0.3.0

data/lib/temporalio/client/schedule_handle.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'temporalio/client/interceptor'
+require 'temporalio/client/schedule'
+
+module Temporalio
+  class Client
+    # Handle for interacting with a schedule. This is usually created via {Client.create_schedule} or
+    # {Client.schedule_handle}.
+    class ScheduleHandle
+      # @return [String] ID of the schedule.
+      attr_reader :id
+
+      # @!visibility private
+      def initialize(client:, id:)
+        @client = client
+        @id = id
+      end
+
+      # Backfill the schedule by going through the specified time periods as if they passed right now.
+      #
+      # @param backfills [Array<Schedule::Backfill>] Backfill periods.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @raise [Error::RPCError] RPC error from call.
+      def backfill(
+        *backfills,
+        rpc_options: nil
+      )
+        raise ArgumentError, 'At least one backfill required' if backfills.empty?
+
+        @client._impl.backfill_schedule(Interceptor::BackfillScheduleInput.new(
+                                          id:,
+                                          backfills:,
+                                          rpc_options:
+                                        ))
+      end
+
+      # Delete this schedule.
+      #
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @raise [Error::RPCError] RPC error from call.
+      def delete(rpc_options: nil)
+        @client._impl.delete_schedule(Interceptor::DeleteScheduleInput.new(
+                                        id:,
+                                        rpc_options:
+                                      ))
+      end
+
+      # Fetch this schedule's description.
+      #
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @return [Schedule::Description] Schedule description.
+      # @raise [Error::RPCError] RPC error from call.
+      def describe(rpc_options: nil)
+        @client._impl.describe_schedule(Interceptor::DescribeScheduleInput.new(
+                                          id:,
+                                          rpc_options:
+                                        ))
+      end
+
+      # Pause the schedule and set a note.
+      #
+      # @param note [String] Note to set on the schedule.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @raise [Error::RPCError] RPC error from call.
+      def pause(note: 'Paused via Ruby SDK', rpc_options: nil)
+        @client._impl.pause_schedule(Interceptor::PauseScheduleInput.new(
+                                       id:,
+                                       note:,
+                                       rpc_options:
+                                     ))
+      end
+
+      # Trigger an action on this schedule to happen immediately.
+      #
+      # @param overlap [Schedule::OverlapPolicy, nil] If set, overrides the schedule's overlap policy.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @raise [Error::RPCError] RPC error from call.
+      def trigger(overlap: nil, rpc_options: nil)
+        @client._impl.trigger_schedule(Interceptor::TriggerScheduleInput.new(
+                                         id:,
+                                         overlap:,
+                                         rpc_options:
+                                       ))
+      end
+
+      # Unpause the schedule and set a note.
+      #
+      # @param note [String] Note to set on the schedule.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @raise [Error::RPCError] RPC error from call.
+      def unpause(note: 'Unpaused via Ruby SDK', rpc_options: nil)
+        @client._impl.unpause_schedule(Interceptor::UnpauseScheduleInput.new(
+                                         id:,
+                                         note:,
+                                         rpc_options:
+                                       ))
+      end
+
+      # Update a schedule using a callback to build the update from the description.
+      #
+      # NOTE: In future versions, the callback may be invoked multiple times in a conflict-resolution loop.
+      #
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      # @yield Block called to obtain the update.
+      # @yieldparam [Schedule::Update::Input] Parameter to the block that contains a description with the schedule to be
+      #   updated.
+      # @yieldreturn [Schedule::Update, nil] The update to apply, or `nil` to not perform an update.
+      #
+      # @raise [Error::RPCError] RPC error from call.
+      def update(rpc_options: nil, &updater)
+        @client._impl.update_schedule(Interceptor::UpdateScheduleInput.new(
+                                        id:,
+                                        updater:,
+                                        rpc_options:
+                                      ))
+      end
+    end
+  end
+end

data/lib/temporalio/client/workflow_execution.rb

@@ -15,17 +15,18 @@ module Temporalio
       # @!visibility private
       def initialize(raw_info, data_converter)
         @raw_info = raw_info
-        @data_converter = data_converter
+        @memo = Internal::ProtoUtils::LazyMemo.new(raw_info.memo, data_converter)
+        @search_attributes = Internal::ProtoUtils::LazySearchAttributes.new(raw_info.search_attributes)
       end
 
       # @return [Time, nil] When the workflow was closed if closed.
       def close_time
-        @raw_info.close_time&.to_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.close_time)
       end
 
       # @return [Time, nil] When this workflow run started or should start.
       def execution_time
-        @raw_info.execution_time&.to_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.execution_time)
       end
 
       # @return [Integer] Number of events in the history.
@@ -40,8 +41,7 @@ module Temporalio
 
       # @return [Hash<String, Object>, nil] Memo for the workflow.
       def memo
-        @memo = Internal::ProtoUtils.memo_from_proto(@raw_info.memo, @data_converter) unless defined?(@memo)
-        @memo
+        @memo.get
       end
 
       # @return [String, nil] ID for the parent workflow if this was started as a child.
@@ -61,15 +61,12 @@ module Temporalio
 
       # @return [SearchAttributes, nil] Current set of search attributes if any.
       def search_attributes
-        unless defined?(@search_attributes)
-          @search_attributes = SearchAttributes.from_proto(@raw_info.search_attributes)
-        end
-        @search_attributes
+        @search_attributes.get
       end
 
       # @return [Time] When the workflow was created.
       def start_time
-        @raw_info.start_time.to_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.start_time) || raise # Never nil
       end
 
       # @return [WorkflowExecutionStatus] Status for the workflow.

data/lib/temporalio/client/workflow_handle.rb

@@ -64,19 +64,14 @@ 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 rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object] Result of the workflow after being converted by the data converter.
       #
       # @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_metadata: nil,
-        rpc_timeout: nil
-      )
+      def result(follow_runs: true, rpc_options: nil)
         # Wait on the close event, following as needed
         hist_run_id = result_run_id
         loop do
@@ -86,8 +81,7 @@ module Temporalio
             event_filter_type: Api::Enums::V1::HistoryEventFilterType::HISTORY_EVENT_FILTER_TYPE_CLOSE_EVENT,
             skip_archival: true,
             specific_run_id: hist_run_id,
-            rpc_metadata:,
-            rpc_timeout:
+            rpc_options:
           ).next
 
           # Check each close type'
@@ -106,13 +100,13 @@ module Temporalio
             raise Error::WorkflowFailedError.new, cause: @client.data_converter.from_failure(attrs.failure)
           when :EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED
             attrs = event.workflow_execution_canceled_event_attributes
-            raise Error::WorkflowFailedError.new, cause: Error::CanceledError.new(
+            raise Error::WorkflowFailedError.new, 'Workflow execution canceled', cause: Error::CanceledError.new(
               'Workflow execution canceled',
               details: @client.data_converter.from_payloads(attrs&.details)
             )
           when :EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED
             attrs = event.workflow_execution_terminated_event_attributes
-            raise Error::WorkflowFailedError.new, cause: Error::TerminatedError.new(
+            raise Error::WorkflowFailedError.new, 'Workflow execution terminated', cause: Error::TerminatedError.new(
               Internal::ProtoUtils.string_or(attrs.reason, 'Workflow execution terminated'),
               details: @client.data_converter.from_payloads(attrs&.details)
             )
@@ -121,7 +115,7 @@ module Temporalio
             hist_run_id = attrs.new_execution_run_id
             next if follow_runs && hist_run_id && !hist_run_id.empty?
 
-            raise Error::WorkflowFailedError.new, cause: Error::TimeoutError.new(
+            raise Error::WorkflowFailedError.new, 'Workflow execution timed out', cause: Error::TimeoutError.new(
               'Workflow execution timed out',
               type: Api::Enums::V1::TimeoutType::TIMEOUT_TYPE_START_TO_CLOSE,
               last_heartbeat_details: []
@@ -142,8 +136,7 @@ module Temporalio
       # Get workflow details. This will get details for the {run_id} if present. To use a different run ID, create a new
       # handle via {Client.workflow_handle}.
       #
-      # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [WorkflowExecution::Description] Workflow description.
       #
@@ -151,15 +144,11 @@ module Temporalio
       #
       # @note Handles created as a result of {Client.start_workflow} will describe the latest workflow with the same
       #   workflow ID even if it is unrelated to the started workflow.
-      def describe(
-        rpc_metadata: nil,
-        rpc_timeout: nil
-      )
+      def describe(rpc_options: nil)
         @client._impl.describe_workflow(Interceptor::DescribeWorkflowInput.new(
                                           workflow_id: id,
                                           run_id:,
-                                          rpc_metadata:,
-                                          rpc_timeout:
+                                          rpc_options:
                                         ))
       end
 
@@ -167,8 +156,7 @@ module Temporalio
       #
       # @param event_filter_type [Api::Enums::V1::HistoryEventFilterType] Types of events to fetch.
       # @param skip_archival [Boolean] Whether to skip archival.
-      # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [WorkflowHistory] Workflow history.
       #
@@ -176,15 +164,13 @@ module Temporalio
       def fetch_history(
         event_filter_type: Api::Enums::V1::HistoryEventFilterType::HISTORY_EVENT_FILTER_TYPE_ALL_EVENT,
         skip_archival: false,
-        rpc_metadata: nil,
-        rpc_timeout: nil
+        rpc_options: nil
       )
         WorkflowHistory.new(
           fetch_history_events(
             event_filter_type:,
             skip_archival:,
-            rpc_metadata:,
-            rpc_timeout:
+            rpc_options:
           ).to_a
         )
       end
@@ -199,8 +185,7 @@ module Temporalio
       # @param skip_archival [Boolean] Whether to skip archival.
       # @param specific_run_id [String, nil] Run ID to fetch events for. Default is the {run_id}. Most users will not
       #   need to set this and instead use the one on the class.
-      # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Enumerator<Api::History::V1::HistoryEvent>] Enumerable events.
       #
@@ -210,8 +195,7 @@ module Temporalio
         event_filter_type: Api::Enums::V1::HistoryEventFilterType::HISTORY_EVENT_FILTER_TYPE_ALL_EVENT,
         skip_archival: false,
         specific_run_id: run_id,
-        rpc_metadata: nil,
-        rpc_timeout: nil
+        rpc_options: nil
       )
         @client._impl.fetch_workflow_history_events(Interceptor::FetchWorkflowHistoryEventsInput.new(
                                                       workflow_id: id,
@@ -219,48 +203,39 @@ module Temporalio
                                                       wait_new_event:,
                                                       event_filter_type:,
                                                       skip_archival:,
-                                                      rpc_metadata:,
-                                                      rpc_timeout:
+                                                      rpc_options:
                                                     ))
       end
 
       # Send a signal to the workflow. This will signal for {run_id} if present. To use a different run ID, create a new
       # handle via {Client.workflow_handle}.
       #
-      # @param signal [String] Signal name.
+      # @param signal [Workflow::Definition::Signal, Symbol, String] Signal definition or name.
       # @param args [Array<Object>] Signal arguments.
-      # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @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_metadata: nil,
-        rpc_timeout: nil
-      )
+      def signal(signal, *args, rpc_options: nil)
         @client._impl.signal_workflow(Interceptor::SignalWorkflowInput.new(
                                         workflow_id: id,
                                         run_id:,
                                         signal:,
                                         args:,
                                         headers: {},
-                                        rpc_metadata:,
-                                        rpc_timeout:
+                                        rpc_options:
                                       ))
       end
 
       # Query the workflow. This will query for {run_id} if present. To use a different run ID, create a new handle via
       # {Client.workflow_handle}.
       #
-      # @param query [String] Query name.
+      # @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 rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Query result.
       #
@@ -274,8 +249,7 @@ module Temporalio
         query,
         *args,
         reject_condition: @client.options.default_workflow_query_reject_condition,
-        rpc_metadata: nil,
-        rpc_timeout: nil
+        rpc_options: nil
       )
         @client._impl.query_workflow(Interceptor::QueryWorkflowInput.new(
                                        workflow_id: id,
@@ -284,21 +258,19 @@ module Temporalio
                                        args:,
                                        reject_condition:,
                                        headers: {},
-                                       rpc_metadata:,
-                                       rpc_timeout:
+                                       rpc_options:
                                      ))
       end
 
       # Send an update request to the workflow and return a handle to it. This will target the workflow with {run_id} if
       # present. To use a different run ID, create a new handle via {Client.workflow_handle}.
       #
-      # @param update [String] Update name.
+      # @param update [Workflow::Definition::Update, Symbol, String] Update definition or name.
       # @param args [Array<Object>] Update arguments.
       # @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 rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [WorkflowUpdateHandle] The update handle.
       #
@@ -308,14 +280,12 @@ 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.
-      # @note WARNING: This API is experimental.
       def start_update(
         update,
         *args,
         wait_for_stage:,
         id: SecureRandom.uuid,
-        rpc_metadata: nil,
-        rpc_timeout: nil
+        rpc_options: nil
       )
         @client._impl.start_workflow_update(Interceptor::StartWorkflowUpdateInput.new(
                                               workflow_id: self.id,
@@ -325,19 +295,17 @@ module Temporalio
                                               args:,
                                               wait_for_stage:,
                                               headers: {},
-                                              rpc_metadata:,
-                                              rpc_timeout:
+                                              rpc_options:
                                             ))
       end
 
       # Send an update request to the workflow and wait for it to complete. This will target the workflow with {run_id}
       # if present. To use a different run ID, create a new handle via {Client.workflow_handle}.
       #
-      # @param update [String] Update name.
+      # @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 rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Update result.
       #
@@ -348,21 +316,13 @@ 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.
-      # @note WARNING: This API is experimental.
-      def execute_update(
-        update,
-        *args,
-        id: SecureRandom.uuid,
-        rpc_metadata: nil,
-        rpc_timeout: nil
-      )
+      def execute_update(update, *args, id: SecureRandom.uuid, rpc_options: nil)
         start_update(
           update,
           *args,
           wait_for_stage: WorkflowUpdateWaitStage::COMPLETED,
           id:,
-          rpc_metadata:,
-          rpc_timeout:
+          rpc_options:
         ).result
       end
 
@@ -373,12 +333,7 @@ module Temporalio
       #   users will not need to set this and instead use the one on the class.
       #
       # @return [WorkflowUpdateHandle] The update handle.
-      #
-      # @note WARNING: This API is experimental.
-      def update_handle(
-        id,
-        specific_run_id: run_id
-      )
+      def update_handle(id, specific_run_id: run_id)
         WorkflowUpdateHandle.new(
           client: @client,
           id:,
@@ -392,23 +347,18 @@ module Temporalio
       # run chain starting from {first_execution_run_id} if present. To create handles with these values, use
       # {Client.workflow_handle}.
       #
-      # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @raise [Error::RPCError] RPC error from call.
       #
       # @note Handles created as a result of signal with start will cancel the latest workflow with the same workflow ID
       #   even if it is unrelated to the started workflow.
-      def cancel(
-        rpc_metadata: nil,
-        rpc_timeout: nil
-      )
+      def cancel(rpc_options: nil)
         @client._impl.cancel_workflow(Interceptor::CancelWorkflowInput.new(
                                         workflow_id: id,
                                         run_id:,
                                         first_execution_run_id:,
-                                        rpc_metadata:,
-                                        rpc_timeout:
+                                        rpc_options:
                                       ))
       end
 
@@ -418,27 +368,20 @@ module Temporalio
       #
       # @param reason [String, nil] Reason for the termination.
       # @param details [Array<Object>] Details to store on the termination.
-      # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @raise [Error::RPCError] RPC error from call.
       #
       # @note Handles created as a result of signal with start will terminate the latest workflow with the same workflow
       #   ID even if it is unrelated to the started workflow.
-      def terminate(
-        reason = nil,
-        details: [],
-        rpc_metadata: nil,
-        rpc_timeout: nil
-      )
+      def terminate(reason = nil, details: [], rpc_options: nil)
         @client._impl.terminate_workflow(Interceptor::TerminateWorkflowInput.new(
                                            workflow_id: id,
                                            run_id:,
                                            first_execution_run_id:,
                                            reason:,
                                            details:,
-                                           rpc_metadata:,
-                                           rpc_timeout:
+                                           rpc_options:
                                          ))
       end
     end

data/lib/temporalio/client/workflow_update_handle.rb

@@ -36,8 +36,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 rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Update result.
       #
@@ -45,13 +44,12 @@ 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_metadata: nil, rpc_timeout: nil)
+      def result(rpc_options: nil)
         @known_outcome ||= @client._impl.poll_workflow_update(Interceptor::PollWorkflowUpdateInput.new(
                                                                 workflow_id:,
                                                                 run_id: workflow_run_id,
                                                                 update_id: id,
-                                                                rpc_metadata:,
-                                                                rpc_timeout:
+                                                                rpc_options:
                                                               ))
 
         if @known_outcome.failure