temporalio 1.2.0 → 1.4.0

data/lib/temporalio/workflow/definition.rb

@@ -110,8 +110,6 @@ module Temporalio
 
         # 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
@@ -732,7 +730,6 @@ module Temporalio
     # @!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

data/lib/temporalio/workflow/info.rb

@@ -23,8 +23,7 @@ module Temporalio
       :task_queue,
       :task_timeout,
       :workflow_id,
-      :workflow_type,
-      keyword_init: true
+      :workflow_type
     )
 
     # Information about the running workflow. This is immutable for the life of the workflow run.
@@ -91,8 +90,7 @@ module Temporalio
       ParentInfo = Struct.new(
         :namespace,
         :run_id,
-        :workflow_id,
-        keyword_init: true
+        :workflow_id
       )
 
       # Information about a root of a workflow.
@@ -106,8 +104,7 @@ module Temporalio
       #   this class or it may break in incompatible ways.
       RootInfo = Struct.new(
         :run_id,
-        :workflow_id,
-        keyword_init: true
+        :workflow_id
       )
     end
   end

data/lib/temporalio/workflow/nexus_client.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Workflow
+    # Client for executing Nexus operations from workflows.
+    #
+    # This is created via {Workflow.create_nexus_client}, it is never instantiated directly.
+    #
+    # WARNING: Nexus support is experimental.
+    class NexusClient
+      # @!visibility private
+      def initialize
+        raise NotImplementedError, 'Cannot instantiate a Nexus client directly'
+      end
+
+      # @return [String] Endpoint name for this client.
+      def endpoint
+        raise NotImplementedError
+      end
+
+      # @return [String] Service name for this client.
+      def service
+        raise NotImplementedError
+      end
+
+      # Start a Nexus operation and return a handle.
+      #
+      # @param operation [Symbol, String] Operation name.
+      # @param arg [Object] Argument for the operation.
+      # @param schedule_to_close_timeout [Float, nil] Total timeout for the operation in seconds.
+      # @param schedule_to_start_timeout [Float, nil] Timeout in seconds for the operation to start executing. If the
+      #   operation has not started within this window, a SCHEDULE_TO_START timeout error is raised.
+      # @param start_to_close_timeout [Float, nil] Timeout in seconds for an async operation to complete after it has
+      #   started. If the operation does not complete within this window, a START_TO_CLOSE timeout error is raised.
+      # @param cancellation_type [NexusOperationCancellationType] How the operation will react to cancellation.
+      # @param summary [String, nil] Optional summary for the operation (appears in UI/CLI).
+      # @param cancellation [Cancellation] Cancellation for the operation.
+      # @param arg_hint [Object, nil] Converter hint for the argument.
+      # @param result_hint [Object, nil] Converter hint for the result.
+      # @return [NexusOperationHandle] Handle to the started operation.
+      def start_operation(
+        operation,
+        arg,
+        schedule_to_close_timeout: nil,
+        schedule_to_start_timeout: nil,
+        start_to_close_timeout: nil,
+        cancellation_type: NexusOperationCancellationType::WAIT_CANCELLATION_COMPLETED,
+        summary: nil,
+        cancellation: Workflow.cancellation,
+        arg_hint: nil,
+        result_hint: nil
+      )
+        raise NotImplementedError
+      end
+
+      # Execute a Nexus operation and wait for the result.
+      #
+      # This is a convenience method that calls {#start_operation} and immediately waits for the result.
+      #
+      # @param operation [Symbol, String] Operation name.
+      # @param arg [Object] Argument for the operation.
+      # @param schedule_to_close_timeout [Float, nil] Total timeout for the operation in seconds.
+      # @param schedule_to_start_timeout [Float, nil] Timeout in seconds for the operation to start executing. If the
+      #   operation has not started within this window, a SCHEDULE_TO_START timeout error is raised.
+      # @param start_to_close_timeout [Float, nil] Timeout in seconds for an async operation to complete after it has
+      #   started. If the operation does not complete within this window, a START_TO_CLOSE timeout error is raised.
+      # @param cancellation_type [NexusOperationCancellationType] How the operation will react to cancellation.
+      # @param summary [String, nil] Optional summary for the operation (appears in UI/CLI).
+      # @param cancellation [Cancellation] Cancellation for the operation.
+      # @param arg_hint [Object, nil] Converter hint for the argument.
+      # @param result_hint [Object, nil] Converter hint for the result.
+      # @return [Object] Result of the operation.
+      # @raise [Error::NexusOperationError] Operation failed.
+      def execute_operation(
+        operation,
+        arg,
+        schedule_to_close_timeout: nil,
+        schedule_to_start_timeout: nil,
+        start_to_close_timeout: nil,
+        cancellation_type: NexusOperationCancellationType::WAIT_CANCELLATION_COMPLETED,
+        summary: nil,
+        cancellation: Workflow.cancellation,
+        arg_hint: nil,
+        result_hint: nil
+      )
+        start_operation(
+          operation, arg, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
+                          cancellation_type:, summary:, cancellation:, arg_hint:, result_hint:
+        ).result
+      end
+    end
+  end
+end

data/lib/temporalio/workflow/nexus_operation_cancellation_type.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/bridge/api'
+
+module Temporalio
+  module Workflow
+    # How a Nexus operation should handle cancellation.
+    #
+    # WARNING: Nexus support is experimental.
+    module NexusOperationCancellationType
+      # Wait for cancellation to complete (default).
+      WAIT_CANCELLATION_COMPLETED = Internal::Bridge::Api::Nexus::NexusOperationCancellationType::WAIT_CANCELLATION_COMPLETED
+      # Abandon the operation without sending a cancellation request.
+      ABANDON = Internal::Bridge::Api::Nexus::NexusOperationCancellationType::ABANDON
+      # Send a cancellation request but do not wait for confirmation.
+      TRY_CANCEL = Internal::Bridge::Api::Nexus::NexusOperationCancellationType::TRY_CANCEL
+      # Wait for the server to confirm the cancellation request was delivered.
+      WAIT_CANCELLATION_REQUESTED = Internal::Bridge::Api::Nexus::NexusOperationCancellationType::WAIT_CANCELLATION_REQUESTED
+    end
+  end
+end

data/lib/temporalio/workflow/nexus_operation_handle.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Workflow
+    # Handle for interacting with a Nexus operation.
+    #
+    # This is created via {NexusClient#start_operation}, it is never instantiated directly.
+    #
+    # WARNING: Nexus support is experimental.
+    class NexusOperationHandle
+      # @!visibility private
+      def initialize
+        raise NotImplementedError, 'Cannot instantiate a Nexus operation handle directly'
+      end
+
+      # @return [String, nil] Operation token for async operations, nil for sync operations.
+      def operation_token
+        raise NotImplementedError
+      end
+
+      # @return [Object, nil] Hint for the result if any.
+      def result_hint
+        raise NotImplementedError
+      end
+
+      # Wait for the result.
+      #
+      # @param result_hint [Object, nil] Override the result hint, or if nil uses the one on the handle.
+      # @return [Object] Result of the Nexus operation.
+      #
+      # @raise [Error::NexusOperationError] Operation failed with +cause+ as the cause.
+      def result(result_hint: nil)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/temporalio/workflow/update_info.rb

@@ -13,8 +13,7 @@ module Temporalio
     #   class or it may break in incompatible ways.
     UpdateInfo = Struct.new(
       :id,
-      :name,
-      keyword_init: true
+      :name
     )
   end
 end

data/lib/temporalio/workflow.rb

@@ -12,6 +12,9 @@ require 'temporalio/workflow/external_workflow_handle'
 require 'temporalio/workflow/future'
 require 'temporalio/workflow/handler_unfinished_policy'
 require 'temporalio/workflow/info'
+require 'temporalio/workflow/nexus_client'
+require 'temporalio/workflow/nexus_operation_cancellation_type'
+require 'temporalio/workflow/nexus_operation_handle'
 require 'temporalio/workflow/parent_close_policy'
 require 'temporalio/workflow/update_info'
 require 'timeout'
@@ -40,6 +43,29 @@ module Temporalio
       _current.continue_as_new_suggested
     end
 
+    # Create a Nexus client for executing operations.
+    #
+    # WARNING: Nexus support is experimental.
+    #
+    # @param endpoint [Symbol, String] Endpoint name.
+    # @param service [Symbol, String] Service name.
+    # @return [NexusClient] Client for executing Nexus operations.
+    def self.create_nexus_client(endpoint:, service:)
+      _current.create_nexus_client(endpoint:, service:)
+    end
+
+    # @return [Array<SuggestContinueAsNewReason::enum>] Reasons the server suggests continue-as-new. Empty if no
+    #   suggestion. This is currently experimental.
+    def self.suggest_continue_as_new_reasons
+      _current.suggest_continue_as_new_reasons
+    end
+
+    # @return [Boolean] Whether the target worker deployment version has changed from the one this workflow is running
+    #   on. This is currently experimental.
+    def self.target_worker_deployment_version_changed?
+      _current.target_worker_deployment_version_changed?
+    end
+
     # Get current details for this workflow that may appear in UI/CLI. Unlike static details set at start, this value
     # can be updated throughout the life of the workflow. This can be in Temporal markdown format and can span multiple
     # lines. This is currently experimental.
@@ -620,7 +646,8 @@ module Temporalio
     # Error that is raised by a workflow out of the primary workflow method to issue a continue-as-new.
     class ContinueAsNewError < Error
       attr_accessor :args, :workflow, :task_queue, :run_timeout, :task_timeout,
-                    :retry_policy, :memo, :search_attributes, :arg_hints, :headers
+                    :retry_policy, :memo, :search_attributes, :arg_hints, :headers,
+                    :initial_versioning_behavior
 
       # Create a continue as new error.
       #
@@ -643,6 +670,9 @@ module Temporalio
       #   workflow definition has arg hints, those are used by default.
       # @param headers [Hash<String, Object>] Headers for the workflow. The default is _not_ carried over from the
       #   current workflow.
+      # @param initial_versioning_behavior [ContinueAsNewVersioningBehavior::enum, nil] Versioning behavior for the
+      #   first task of the new run. Set to {ContinueAsNewVersioningBehavior::AUTO_UPGRADE} to upgrade a pinned workflow
+      #   to the latest version on continue-as-new. This is currently experimental.
       def initialize(
         *args,
         workflow: nil,
@@ -653,7 +683,8 @@ module Temporalio
         memo: nil,
         search_attributes: nil,
         arg_hints: nil,
-        headers: {}
+        headers: {},
+        initial_versioning_behavior: nil
       )
         super('Continue as new')
         @args = args
@@ -666,6 +697,7 @@ module Temporalio
         @search_attributes = search_attributes
         @arg_hints = arg_hints
         @headers = headers
+        @initial_versioning_behavior = initial_versioning_behavior
         Workflow._current.initialize_continue_as_new_error(self)
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: temporalio
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Temporal Technologies Inc
@@ -62,7 +62,10 @@ files:
 - lib/temporalio/api.rb
 - lib/temporalio/api/activity/v1/message.rb
 - lib/temporalio/api/batch/v1/message.rb
+- lib/temporalio/api/callback/v1/message.rb
 - lib/temporalio/api/cloud/account/v1/message.rb
+- lib/temporalio/api/cloud/auditlog/v1/message.rb
+- lib/temporalio/api/cloud/billing/v1/message.rb
 - lib/temporalio/api/cloud/cloudservice.rb
 - lib/temporalio/api/cloud/cloudservice/v1/request_response.rb
 - lib/temporalio/api/cloud/cloudservice/v1/service.rb
@@ -78,6 +81,9 @@ files:
 - lib/temporalio/api/command/v1/message.rb
 - lib/temporalio/api/common/v1/grpc_status.rb
 - lib/temporalio/api/common/v1/message.rb
+- lib/temporalio/api/compute/v1/config.rb
+- lib/temporalio/api/compute/v1/provider.rb
+- lib/temporalio/api/compute/v1/scaler.rb
 - lib/temporalio/api/deployment/v1/message.rb
 - lib/temporalio/api/enums/v1/activity.rb
 - lib/temporalio/api/enums/v1/batch_operation.rb
@@ -101,16 +107,21 @@ files:
 - lib/temporalio/api/history/v1/message.rb
 - lib/temporalio/api/namespace/v1/message.rb
 - lib/temporalio/api/nexus/v1/message.rb
+- lib/temporalio/api/nexusservices/workerservice/v1/request_response.rb
 - lib/temporalio/api/operatorservice.rb
 - lib/temporalio/api/operatorservice/v1/request_response.rb
 - lib/temporalio/api/operatorservice/v1/service.rb
 - lib/temporalio/api/payload_visitor.rb
+- lib/temporalio/api/protoc_gen_openapiv2/options/annotations.rb
+- lib/temporalio/api/protoc_gen_openapiv2/options/openapiv2.rb
 - lib/temporalio/api/protocol/v1/message.rb
+- lib/temporalio/api/protometa/v1/annotations.rb
 - lib/temporalio/api/query/v1/message.rb
 - lib/temporalio/api/replication/v1/message.rb
 - lib/temporalio/api/rules/v1/message.rb
 - lib/temporalio/api/schedule/v1/message.rb
 - lib/temporalio/api/sdk/v1/enhanced_stack_trace.rb
+- lib/temporalio/api/sdk/v1/external_storage.rb
 - lib/temporalio/api/sdk/v1/task_complete_metadata.rb
 - lib/temporalio/api/sdk/v1/user_metadata.rb
 - lib/temporalio/api/sdk/v1/worker_config.rb
@@ -197,6 +208,8 @@ files:
 - lib/temporalio/internal/worker/workflow_instance/handler_hash.rb
 - lib/temporalio/internal/worker/workflow_instance/illegal_call_tracer.rb
 - lib/temporalio/internal/worker/workflow_instance/inbound_implementation.rb
+- lib/temporalio/internal/worker/workflow_instance/nexus_client.rb
+- lib/temporalio/internal/worker/workflow_instance/nexus_operation_handle.rb
 - lib/temporalio/internal/worker/workflow_instance/outbound_implementation.rb
 - lib/temporalio/internal/worker/workflow_instance/replay_safe_logger.rb
 - lib/temporalio/internal/worker/workflow_instance/replay_safe_metric.rb
@@ -239,6 +252,9 @@ files:
 - lib/temporalio/workflow/future.rb
 - lib/temporalio/workflow/handler_unfinished_policy.rb
 - lib/temporalio/workflow/info.rb
+- lib/temporalio/workflow/nexus_client.rb
+- lib/temporalio/workflow/nexus_operation_cancellation_type.rb
+- lib/temporalio/workflow/nexus_operation_handle.rb
 - lib/temporalio/workflow/parent_close_policy.rb
 - lib/temporalio/workflow/update_info.rb
 - lib/temporalio/workflow_history.rb
@@ -264,7 +280,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Temporal.io Ruby SDK
 test_files: []