temporalio 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f975392bb8cb3a4fddc500af9bed6b6c1462a2c959ff32590082f71e0506900d
-  data.tar.gz: 0662e05ad2df429a11e9afca0c53310353ec483e61149eccaedcc636ed6cb184
+  metadata.gz: 402b9eb0039d985a8e98f5cebfcae841af4483c06d070a76f9f3b213b4853049
+  data.tar.gz: 2d2d14d2e8d13d825db718267ea086fedefc5562843e1eb584bbd20b2cf02c90
 SHA512:
-  metadata.gz: 07007a45cb8c01381cec79c406fe2f43ea0146b57a99599057d1d5784e3e6d110c765c01ecd7370936dba8123a6f7e2c245456c412ac5125e55e1bb3d41c2e5e
-  data.tar.gz: fb1db70aa8ab4ca4d42c107830b544576996fa8411664d8adaae2e894f6e424032c25e855d607fc24e30b53167b2cf023205f1f0e568002c80cbb42170798554
+  metadata.gz: 90dda134d91f20010315e248caf76065f21c4d806219612b14e20823ed947480129aea0098c602d6b639ecc296e9a22c0694fae484b46aad630432307c4c0cc6
+  data.tar.gz: f64e68cb9b0a58be826314ea1a40dff5bd86ea5b230eebea5ba129a9f6100b72ce454247b314781c2541b784ac4141681f0a2da3f03406996c5c030426aa1c61

data/Cargo.lock

@@ -2,6 +2,15 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "addr2line"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
+dependencies = [
+ "gimli",
+]
+
 [[package]]
 name = "adler2"
 version = "2.0.1"
@@ -262,6 +271,21 @@ dependencies = [
  "rand 0.8.5",
 ]
 
+[[package]]
+name = "backtrace"
+version = "0.3.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "object",
+ "rustc-demangle",
+ "windows-link 0.2.1",
+]
+
 [[package]]
 name = "base64"
 version = "0.21.7"
@@ -345,9 +369,9 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
 [[package]]
 name = "bytes"
-version = "1.11.0"
+version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b35204fbdc0b3f4446b89fc1ac2cf84a8a68971995d0bf2e925ec7cd960f9cb3"
+checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "bzip2"
@@ -730,6 +754,22 @@ dependencies = [
  "unicode-xid",
 ]
 
+[[package]]
+name = "dhat"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "98cd11d84628e233de0ce467de10b8633f4ddaecafadefc86e13b84b8739b827"
+dependencies = [
+ "backtrace",
+ "lazy_static",
+ "mintex",
+ "parking_lot",
+ "rustc-hash 1.1.0",
+ "serde",
+ "serde_json",
+ "thousands",
+]
+
 [[package]]
 name = "dirs"
 version = "6.0.0"
@@ -1056,6 +1096,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "gimli"
+version = "0.32.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
+
 [[package]]
 name = "glob"
 version = "0.3.3"
@@ -1694,6 +1740,12 @@ dependencies = [
  "simd-adler32",
 ]
 
+[[package]]
+name = "mintex"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c505b3e17ed6b70a7ed2e67fbb2c560ee327353556120d6e72f5232b6880d536"
+
 [[package]]
 name = "mio"
 version = "1.1.1"
@@ -1799,6 +1851,15 @@ dependencies = [
  "objc2-core-foundation",
 ]
 
+[[package]]
+name = "object"
+version = "0.37.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.3"
@@ -2656,6 +2717,12 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "rustc-demangle"
+version = "0.1.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d"
+
 [[package]]
 name = "rustc-hash"
 version = "1.1.0"
@@ -3172,6 +3239,7 @@ dependencies = [
  "anyhow",
  "assert_matches",
  "async-trait",
+ "backoff",
  "bimap",
  "bon",
  "bytes",
@@ -3238,6 +3306,7 @@ name = "temporalio_bridge"
 version = "0.1.0"
 dependencies = [
  "async-trait",
+ "dhat",
  "futures",
  "log",
  "magnus",
@@ -3310,6 +3379,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "thousands"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3bf63baf9f5039dadc247375c29eb13706706cfde997d0330d05aa63a77d8820"
+
 [[package]]
 name = "thread_local"
 version = "1.1.9"

data/ext/Cargo.toml

@@ -26,3 +26,7 @@ tokio-util = "0.7"
 tonic = { workspace = true }
 tracing = "0.1"
 url = "2.5"
+dhat = { version = "0.3", optional = true }
+
+[features]
+dhat-heap = ["dhat"]

data/lib/temporalio/client.rb

@@ -298,7 +298,6 @@ module Temporalio
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
     # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
-    #   This is currently experimental.
     # @param priority [Priority] Priority of the workflow. This is currently experimental.
     # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
     #   workflow definition has arg hints, those are used by default.
@@ -392,7 +391,6 @@ module Temporalio
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
     # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
-    #   This is currently experimental.
     # @param priority [Priority] Priority for the workflow. This is currently experimental.
     # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
     #   workflow definition has arg hints, those are used by default.

data/lib/temporalio/common_enums.rb

@@ -40,8 +40,6 @@ module Temporalio
   end
 
   # Specifies when a workflow might move from a worker of one Build Id to another.
-  #
-  # WARNING: Experimental API.
   module VersioningBehavior
     # Unspecified versioning behavior. By default, workers opting into worker versioning will
     # be required to specify a behavior.

data/lib/temporalio/contrib/open_telemetry.rb

@@ -67,6 +67,11 @@ module Temporalio
           headers[@header_key] = carrier unless carrier.empty?
         end
 
+        # @!visibility private
+        def _propagator
+          @propagator
+        end
+
         # @!visibility private
         def _attach_context(headers)
           context = _context_from_headers(headers)
@@ -402,6 +407,22 @@ module Temporalio
             super
           end
 
+          # @!visibility private
+          def start_nexus_operation(input)
+            # Nexus headers are string-to-string maps (not payload-based like activity/workflow headers)
+            # so we inject the tracing context directly into the headers instead of nesting under a key
+            span = Workflow.completed_span("StartNexusOperation:#{input.service}/#{input.operation}", kind: :client)
+            Temporalio::Workflow::Unsafe.durable_scheduler_disabled do
+              if span
+                @root._propagator.inject(
+                  input.headers,
+                  context: ::OpenTelemetry::Trace.context_with_span(span)
+                )
+              end
+            end
+            super
+          end
+
           # @!visibility private
           def _apply_span_to_headers(headers, span)
             # See WorkflowInbound#_attach_context comments for why we have to disable scheduler even for these simple

data/lib/temporalio/converters/failure_converter.rb

@@ -84,6 +84,18 @@ module Temporalio
             started_event_id: error.started_event_id,
             retry_state: error.retry_state
           )
+        when Error::NexusOperationError
+          failure.nexus_operation_execution_failure_info = Api::Failure::V1::NexusOperationFailureInfo.new(
+            endpoint: error.endpoint,
+            service: error.service,
+            operation: error.operation,
+            operation_token: error.operation_token || ''
+          )
+        when Error::NexusHandlerError
+          failure.nexus_handler_failure_info = Api::Failure::V1::NexusHandlerFailureInfo.new(
+            type: error.error_type.to_s,
+            retry_behavior: error.retry_behavior
+          )
         else
           failure.application_failure_info = Api::Failure::V1::ApplicationFailureInfo.new(
             type: error.class.name.to_s.split('::').last
@@ -190,6 +202,24 @@ module Temporalio
                       zero_means_nil: true
                     )
                   )
+                elsif failure.nexus_operation_execution_failure_info
+                  token = failure.nexus_operation_execution_failure_info.operation_token
+                  Error::NexusOperationError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Nexus operation error'),
+                    endpoint: failure.nexus_operation_execution_failure_info.endpoint,
+                    service: failure.nexus_operation_execution_failure_info.service,
+                    operation: failure.nexus_operation_execution_failure_info.operation,
+                    operation_token: token.empty? ? nil : token
+                  )
+                elsif failure.nexus_handler_failure_info
+                  Error::NexusHandlerError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Nexus handler error'),
+                    error_type: failure.nexus_handler_failure_info.type,
+                    retry_behavior: Internal::ProtoUtils.enum_to_int(
+                      Api::Enums::V1::NexusHandlerErrorRetryBehavior,
+                      failure.nexus_handler_failure_info.retry_behavior
+                    )
+                  )
                 else
                   Error::Failure.new(Internal::ProtoUtils.string_or(failure.message, 'Failure error'))
                 end

data/lib/temporalio/env_config.rb

@@ -4,9 +4,7 @@ require 'pathname'
 require 'temporalio/internal/bridge'
 
 module Temporalio
-  # Environment and file-based configuration for Temporal clients
-  #
-  # WARNING: Experimental API.
+  # Environment and file-based configuration for Temporal clients.
   module EnvConfig
     # This module provides utilities to load Temporal client configuration from TOML files
     # and environment variables.

data/lib/temporalio/error/failure.rb

@@ -233,5 +233,71 @@ module Temporalio
         @retry_state = retry_state
       end
     end
+
+    # Error raised on Nexus operation failure.
+    #
+    # WARNING: Nexus support is experimental.
+    class NexusOperationError < Failure
+      # @return [String] Nexus endpoint.
+      attr_reader :endpoint
+      # @return [String] Nexus service.
+      attr_reader :service
+      # @return [String] Nexus operation.
+      attr_reader :operation
+      # @return [String, nil] Operation token for async operations.
+      attr_reader :operation_token
+
+      # @!visibility private
+      def initialize(
+        message,
+        endpoint:,
+        service:,
+        operation:,
+        operation_token:
+      )
+        super(message)
+        @endpoint = endpoint
+        @service = service
+        @operation = operation
+        @operation_token = operation_token
+      end
+    end
+
+    # Error raised from a Nexus handler.
+    #
+    # WARNING: Nexus support is experimental.
+    class NexusHandlerError < Failure
+      # @return [Symbol] Error type from the handler.
+      attr_reader :error_type
+
+      # @return [RetryBehavior] Retry behavior for the error.
+      attr_reader :retry_behavior
+
+      # @!visibility private
+      def initialize(
+        message,
+        error_type:,
+        retry_behavior:
+      )
+        super(message)
+        @error_type = error_type.to_sym
+        @retry_behavior = retry_behavior
+      end
+
+      # Nexus handler error retry behavior.
+      module RetryBehavior
+        # Unspecified retry behavior.
+        UNSPECIFIED =
+          Api::Enums::V1::NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED
+
+        # Retryable error.
+        RETRYABLE =
+          Api::Enums::V1::NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE
+
+        # Non-retryable error.
+        NON_RETRYABLE =
+          Api::Enums::V1::NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE
+      end
+    end
   end
 end

data/lib/temporalio/internal/worker/workflow_instance/context.rb

@@ -6,6 +6,7 @@ require 'temporalio/internal/bridge/api'
 require 'temporalio/internal/proto_utils'
 require 'temporalio/internal/worker/workflow_instance'
 require 'temporalio/internal/worker/workflow_instance/external_workflow_handle'
+require 'temporalio/internal/worker/workflow_instance/nexus_client'
 require 'temporalio/worker/interceptor'
 require 'temporalio/workflow'
 
@@ -32,6 +33,10 @@ module Temporalio
             @instance.continue_as_new_suggested
           end
 
+          def create_nexus_client(endpoint:, service:)
+            NexusClient.new(endpoint:, service:, outbound: @outbound)
+          end
+
           def current_details
             @instance.current_details || ''
           end

data/lib/temporalio/internal/worker/workflow_instance/nexus_client.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require 'temporalio/workflow/nexus_client'
+
+module Temporalio
+  module Internal
+    module Worker
+      class WorkflowInstance
+        # Implementation of the Nexus client.
+        class NexusClient < Workflow::NexusClient
+          attr_reader :endpoint, :service
+
+          def initialize(endpoint:, service:, outbound:) # rubocop:disable Lint/MissingSuper
+            @endpoint = endpoint.to_s
+            @service = service.to_s
+            @outbound = outbound
+          end
+
+          def start_operation(operation, arg, schedule_to_close_timeout: nil, cancellation_type: nil, summary: nil,
+                              cancellation: Workflow.cancellation, arg_hint: nil, result_hint: nil)
+            @outbound.start_nexus_operation(
+              Temporalio::Worker::Interceptor::Workflow::StartNexusOperationInput.new(
+                endpoint: @endpoint,
+                service: @service,
+                operation: operation.to_s,
+                arg:,
+                schedule_to_close_timeout:,
+                cancellation_type:,
+                summary:,
+                cancellation:,
+                arg_hint:,
+                result_hint:,
+                headers: {}
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/internal/worker/workflow_instance/nexus_operation_handle.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'temporalio/cancellation'
+require 'temporalio/workflow'
+require 'temporalio/workflow/nexus_operation_handle'
+
+module Temporalio
+  module Internal
+    module Worker
+      class WorkflowInstance
+        # Implementation of the Nexus operation handle.
+        class NexusOperationHandle < Workflow::NexusOperationHandle
+          attr_reader :operation_token, :result_hint
+
+          def initialize(operation_token:, instance:, cancellation:, cancel_callback_key:, # rubocop:disable Lint/MissingSuper
+                         result_hint:)
+            @operation_token = operation_token
+            @instance = instance
+            @cancellation = cancellation
+            @cancel_callback_key = cancel_callback_key
+            @result_hint = result_hint
+            @resolution = nil
+          end
+
+          def result(result_hint: nil)
+            # Use detached cancellation like child workflow to avoid interrupting result wait
+            Workflow.wait_condition(cancellation: Cancellation.new) { @resolution }
+
+            case @resolution.status
+            when :completed
+              @instance.payload_converter.from_payload(@resolution.completed, hint: result_hint || @result_hint)
+            when :failed
+              raise @instance.failure_converter.from_failure(@resolution.failed, @instance.payload_converter)
+            when :cancelled
+              raise @instance.failure_converter.from_failure(@resolution.cancelled, @instance.payload_converter)
+            when :timed_out
+              raise @instance.failure_converter.from_failure(@resolution.timed_out, @instance.payload_converter)
+            else
+              raise "Unrecognized Nexus operation result status: #{@resolution.status}"
+            end
+          end
+
+          def _resolve(resolution)
+            @cancellation.remove_cancel_callback(@cancel_callback_key)
+            @resolution = resolution
+          end
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/internal/worker/workflow_instance/outbound_implementation.rb

@@ -6,6 +6,7 @@ require 'temporalio/error'
 require 'temporalio/internal/bridge/api'
 require 'temporalio/internal/proto_utils'
 require 'temporalio/internal/worker/workflow_instance'
+require 'temporalio/internal/worker/workflow_instance/nexus_operation_handle'
 require 'temporalio/worker/interceptor'
 require 'temporalio/workflow'
 require 'temporalio/workflow/child_workflow_handle'
@@ -22,6 +23,7 @@ module Temporalio
             @activity_counter = 0
             @timer_counter = 0
             @child_counter = 0
+            @nexus_operation_counter = 0
             @external_signal_counter = 0
             @external_cancel_counter = 0
           end
@@ -429,6 +431,72 @@ module Temporalio
               raise "Unknown resolution status: #{resolution.status}"
             end
           end
+
+          def start_nexus_operation(input)
+            raise Error::CanceledError, 'Nexus operation canceled before scheduled' if input.cancellation.canceled?
+
+            # Add the command
+            seq = (@nexus_operation_counter += 1)
+            @instance.add_command(
+              Bridge::Api::WorkflowCommands::WorkflowCommand.new(
+                schedule_nexus_operation: Bridge::Api::WorkflowCommands::ScheduleNexusOperation.new(
+                  seq:,
+                  endpoint: input.endpoint,
+                  service: input.service,
+                  operation: input.operation,
+                  input: @instance.payload_converter.to_payload(input.arg, hint: input.arg_hint),
+                  schedule_to_close_timeout: ProtoUtils.seconds_to_duration(input.schedule_to_close_timeout),
+                  nexus_header: input.headers,
+                  cancellation_type: input.cancellation_type
+                ),
+                user_metadata: ProtoUtils.to_user_metadata(input.summary, nil, @instance.payload_converter)
+              )
+            )
+
+            # Set as pending start
+            @instance.pending_nexus_operation_starts[seq] = Fiber.current
+
+            # Register cancel callback
+            cancel_callback_key = input.cancellation.add_cancel_callback do
+              # Send cancel if in start or pending
+              if @instance.pending_nexus_operation_starts.include?(seq) ||
+                 @instance.pending_nexus_operations.include?(seq)
+                @instance.add_command(
+                  Bridge::Api::WorkflowCommands::WorkflowCommand.new(
+                    request_cancel_nexus_operation: Bridge::Api::WorkflowCommands::RequestCancelNexusOperation.new(
+                      seq:
+                    )
+                  )
+                )
+              end
+            end
+
+            # Wait for start resolution
+            resolution = begin
+              Fiber.yield
+            ensure
+              # Remove pending start
+              @instance.pending_nexus_operation_starts.delete(seq)
+            end
+
+            # Handle start failure
+            if resolution.failed
+              input.cancellation.remove_cancel_callback(cancel_callback_key)
+              raise @instance.failure_converter.from_failure(resolution.failed, @instance.payload_converter)
+            end
+
+            # Create handle and add to pending operations (result will come via resolve_nexus_operation)
+            handle = NexusOperationHandle.new(
+              operation_token: resolution.operation_token,
+              instance: @instance,
+              cancellation: input.cancellation,
+              cancel_callback_key:,
+              result_hint: input.result_hint
+            )
+            @instance.pending_nexus_operations[seq] = handle
+
+            handle
+          end
         end
       end
     end

data/lib/temporalio/internal/worker/workflow_instance.rb

@@ -54,6 +54,7 @@ module Temporalio
 
         attr_reader :context, :logger, :info, :scheduler, :disable_eager_activity_execution, :pending_activities,
                     :pending_timers, :pending_child_workflow_starts, :pending_child_workflows,
+                    :pending_nexus_operation_starts, :pending_nexus_operations,
                     :pending_external_signals, :pending_external_cancels, :in_progress_handlers, :payload_converter,
                     :failure_converter, :cancellation, :continue_as_new_suggested, :current_deployment_version,
                     :current_history_length, :current_history_size, :replaying, :random,
@@ -79,6 +80,8 @@ module Temporalio
           @pending_timers = {} # Keyed by sequence, value is fiber to resume with proto result
           @pending_child_workflow_starts = {} # Keyed by sequence, value is fiber to resume with proto result
           @pending_child_workflows = {} # Keyed by sequence, value is ChildWorkflowHandle to resolve with proto result
+          @pending_nexus_operation_starts = {} # Keyed by sequence, value is fiber to resume with proto result
+          @pending_nexus_operations = {} # Keyed by sequence, value is NexusOperationHandle to resolve with proto result
           @pending_external_signals = {} # Keyed by sequence, value is fiber to resume with proto result
           @pending_external_cancels = {} # Keyed by sequence, value is fiber to resume with proto result
           @buffered_signals = {} # Keyed by signal name, value is array of signal jobs
@@ -369,6 +372,14 @@ module Temporalio
             pending_child_workflows[job.resolve_child_workflow_execution.seq]&._resolve(
               job.resolve_child_workflow_execution.result
             )
+          when :resolve_nexus_operation_start
+            pending_nexus_operation_starts[job.resolve_nexus_operation_start.seq]&.resume(
+              job.resolve_nexus_operation_start
+            )
+          when :resolve_nexus_operation
+            pending_nexus_operations[job.resolve_nexus_operation.seq]&._resolve(
+              job.resolve_nexus_operation.result
+            )
           when :resolve_signal_external_workflow
             pending_external_signals[job.resolve_signal_external_workflow.seq]&.resume(
               job.resolve_signal_external_workflow

data/lib/temporalio/testing/workflow_environment.rb

@@ -2,6 +2,7 @@
 
 require 'delegate'
 require 'temporalio/api'
+require 'temporalio/api/operatorservice/v1/request_response'
 require 'temporalio/api/testservice/v1/request_response'
 require 'temporalio/client'
 require 'temporalio/client/connection/test_service'
@@ -264,6 +265,45 @@ module Temporalio
         Time.now
       end
 
+      # Create Nexus endpoint on this test environment.
+      #
+      # WARNING: Nexus support is experimental.
+      #
+      # @param name [String] Endpoint name.
+      # @param task_queue [String] Task queue for the endpoint.
+      # @return [Temporalio::Api::Nexus::V1::Endpoint] Created endpoint.
+      def create_nexus_endpoint(name:, task_queue:)
+        resp = client.connection.operator_service.create_nexus_endpoint(
+          Temporalio::Api::OperatorService::V1::CreateNexusEndpointRequest.new(
+            spec: Temporalio::Api::Nexus::V1::EndpointSpec.new(
+              name:,
+              target: Temporalio::Api::Nexus::V1::EndpointTarget.new(
+                worker: Temporalio::Api::Nexus::V1::EndpointTarget::Worker.new(
+                  namespace: client.namespace,
+                  task_queue:
+                )
+              )
+            )
+          )
+        )
+        resp.endpoint
+      end
+
+      # Delete Nexus endpoint on this test environment.
+      #
+      # WARNING: Nexus support is experimental.
+      #
+      # @param endpoint [Temporalio::Api::Nexus::V1::Endpoint] Endpoint to delete.
+      def delete_nexus_endpoint(endpoint)
+        client.connection.operator_service.delete_nexus_endpoint(
+          Temporalio::Api::OperatorService::V1::DeleteNexusEndpointRequest.new(
+            id: endpoint.id,
+            version: endpoint.version
+          )
+        )
+        nil
+      end
+
       # Run a block with automatic time skipping disabled. This just runs the block for environments that don't support
       # time skipping.
       #

data/lib/temporalio/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Temporalio
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/lib/temporalio/versioning_override.rb

@@ -5,8 +5,6 @@ require 'temporalio/worker_deployment_version'
 module Temporalio
   # Base class for version overrides that can be provided in start workflow options.
   # Used to control the versioning behavior of workflows started with this override.
-  #
-  # WARNING: Experimental API.
   class VersioningOverride
     # @!visibility private
     def _to_proto

data/lib/temporalio/worker/deployment_options.rb

@@ -13,8 +13,6 @@ module Temporalio
 
     # Options for configuring the Worker Versioning feature.
     #
-    # WARNING: Deployment-based versioning is experimental and APIs may change.
-    #
     # @!attribute version
     #   @return [WorkerDeploymentVersion] The worker deployment version.
     # @!attribute use_worker_versioning

data/lib/temporalio/worker/interceptor.rb

@@ -300,6 +300,23 @@ module Temporalio
           :headers
         )
 
+        # Input for {Outbound.start_nexus_operation}.
+        #
+        # WARNING: Nexus support is experimental.
+        StartNexusOperationInput = Data.define(
+          :endpoint,
+          :service,
+          :operation,
+          :arg,
+          :schedule_to_close_timeout,
+          :cancellation_type,
+          :summary,
+          :cancellation,
+          :arg_hint,
+          :result_hint,
+          :headers
+        )
+
         # Outbound interceptor for intercepting outbound workflow calls. This should be extended by users needing to
         # intercept workflow calls.
         class Outbound
@@ -371,6 +388,16 @@ module Temporalio
           def start_child_workflow(input)
             @next_interceptor.start_child_workflow(input)
           end
+
+          # Start Nexus operation.
+          #
+          # WARNING: Nexus support is experimental.
+          #
+          # @param input [StartNexusOperationInput] Input.
+          # @return [Workflow::NexusOperationHandle] Nexus operation handle.
+          def start_nexus_operation(input)
+            @next_interceptor.start_nexus_operation(input)
+          end
         end
       end
     end

data/lib/temporalio/worker/workflow_executor/thread_pool.rb

@@ -49,7 +49,7 @@ module Temporalio
               # If not found, get a new one either by creating if not enough or find the one with the fewest.
               new_worker = if @workers.size < @max_threads
                              created_worker = Worker.new(self)
-                             @workers << Worker.new(self)
+                             @workers << created_worker
                              created_worker
                            else
                              @workers.min_by(&:workflow_count)

data/lib/temporalio/worker.rb

@@ -425,7 +425,6 @@ module Temporalio
     #   scheduler will fail. Instead of setting this to true, users are encouraged to use {Workflow::Unsafe.io_enabled}
     #   with a block for narrower enabling of IO.
     # @param deployment_options [DeploymentOptions, nil] Deployment options for the worker.
-    #   WARNING: This is an experimental feature and may change in the future.
     # @param workflow_task_poller_behavior [PollerBehavior] Specify the behavior of workflow task
     #   polling. Defaults to a 5-poller maximum.
     # @param activity_task_poller_behavior [PollerBehavior] Specify the behavior of activity task

data/lib/temporalio/worker_deployment_version.rb

@@ -9,8 +9,6 @@ module Temporalio
   )
 
   # Represents the version of a specific worker deployment.
-  #
-  # WARNING: Experimental API.
   class WorkerDeploymentVersion
     # Parse a version from a canonical string, which must be in the format
     # `<deployment_name>.<build_id>`. Deployment name must not have a `.` in it.

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/nexus_client.rb

@@ -0,0 +1,81 @@
+# 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 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,
+        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 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,
+        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:, 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.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,17 @@ 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
+
     # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: temporalio
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Temporal Technologies Inc
@@ -197,6 +197,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 +241,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