temporalio 0.4.0 → 0.6.0

data/lib/temporalio/workflow.rb

@@ -2,6 +2,8 @@
 
 require 'random/formatter'
 require 'temporalio/error'
+require 'temporalio/internal/worker/workflow_instance'
+require 'temporalio/priority'
 require 'temporalio/workflow/activity_cancellation_type'
 require 'temporalio/workflow/child_workflow_cancellation_type'
 require 'temporalio/workflow/child_workflow_handle'
@@ -56,6 +58,18 @@ module Temporalio
       _current.current_details = details
     end
 
+    # Get the deployment version of the worker which executed the current Workflow Task.
+    #
+    # May be nil if the task was completed by a worker without a deployment version or build id. If
+    # this worker is the one executing this task for the first time and has a deployment version
+    # set, then its ID will be used. This value may change over the lifetime of the workflow run,
+    # but is deterministic and safe to use for branching. This is currently experimental.
+    #
+    # @return [WorkerDeploymentVersion, nil] the current deployment version if any.
+    def self.current_deployment_version
+      _current.current_deployment_version
+    end
+
     # @return [Integer] Current number of events in history. This value is the current history event count up until the
     #   current task. Note, this value may not be up to date when accessed in a query.
     def self.current_history_length
@@ -118,6 +132,11 @@ module Temporalio
     #   optimization on some servers that sends activities back to the same worker as the calling workflow if they can
     #   run there. If `false` (the default), eager execution may still be disabled at the worker level or may not be
     #   requested due to lack of available slots.
+    # @param priority [Priority] Priority of the activity. This is currently experimental.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+    #   activity definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the activity
+    #   definition has result hint, it is used by default.
     #
     # @return [Object] Result of the activity.
     # @raise [Error::ActivityError] Activity failed (and retry was disabled or exhausted).
@@ -136,12 +155,16 @@ module Temporalio
       cancellation: Workflow.cancellation,
       cancellation_type: ActivityCancellationType::TRY_CANCEL,
       activity_id: nil,
-      disable_eager_execution: false
+      disable_eager_execution: false,
+      priority: Priority.default,
+      arg_hints: nil,
+      result_hint: nil
     )
       _current.execute_activity(
         activity, *args,
         task_queue:, summary:, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
-        heartbeat_timeout:, retry_policy:, cancellation:, cancellation_type:, activity_id:, disable_eager_execution:
+        heartbeat_timeout:, retry_policy:, cancellation:, cancellation_type:, activity_id:, disable_eager_execution:,
+        priority:, arg_hints:, result_hint:
       )
     end
 
@@ -163,13 +186,16 @@ module Temporalio
       retry_policy: nil,
       cron_schedule: nil,
       memo: nil,
-      search_attributes: nil
+      search_attributes: nil,
+      priority: Priority.default,
+      arg_hints: nil,
+      result_hint: nil
     )
       start_child_workflow(
         workflow, *args,
         id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
         parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
-        retry_policy:, cron_schedule:, memo:, search_attributes:
+        retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, arg_hints:, result_hint:
       ).result
     end
 
@@ -200,6 +226,10 @@ module Temporalio
     #   workflow.
     # @param activity_id [String, nil] Optional unique identifier for the activity. This is an advanced setting that
     #   should not be set unless users are sure they need to. Contact Temporal before setting this value.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+    #   activity definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the activity
+    #   definition has result hint, it is used by default.
     #
     # @return [Object] Result of the activity.
     # @raise [Error::ActivityError] Activity failed (and retry was disabled or exhausted).
@@ -215,12 +245,15 @@ module Temporalio
       local_retry_threshold: nil,
       cancellation: Workflow.cancellation,
       cancellation_type: ActivityCancellationType::TRY_CANCEL,
-      activity_id: nil
+      activity_id: nil,
+      arg_hints: nil,
+      result_hint: nil
     )
       _current.execute_local_activity(
         activity, *args,
         schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
-        retry_policy:, local_retry_threshold:, cancellation:, cancellation_type:, activity_id:
+        retry_policy:, local_retry_threshold:, cancellation:, cancellation_type:,
+        activity_id:, arg_hints:, result_hint:
       )
     end
 
@@ -360,6 +393,11 @@ module Temporalio
     # @param cron_schedule [String, nil] Cron schedule. Users should use schedules instead of this.
     # @param memo [Hash{String, Symbol => Object}, nil] Memo for the workflow.
     # @param search_attributes [SearchAttributes, nil] Search attributes for the workflow.
+    # @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.
+    # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the workflow
+    #   definition has result hint, it is used by default.
     #
     # @return [ChildWorkflowHandle] Workflow handle to the started workflow.
     # @raise [Error::WorkflowAlreadyStartedError] Workflow already exists for the ID.
@@ -381,13 +419,16 @@ module Temporalio
       retry_policy: nil,
       cron_schedule: nil,
       memo: nil,
-      search_attributes: nil
+      search_attributes: nil,
+      priority: Priority.default,
+      arg_hints: nil,
+      result_hint: nil
     )
       _current.start_child_workflow(
         workflow, *args,
         id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
         parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
-        retry_policy:, cron_schedule:, memo:, search_attributes:
+        retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, arg_hints:, result_hint:
       )
     end
 
@@ -497,25 +538,79 @@ module Temporalio
       # Run a block of code with illegal call tracing disabled. Users should be cautious about using this as it can
       # often signify unsafe code.
       #
+      # If this is invoked outside of a workflow, it just runs the block.
+      #
       # @yield Block to run with call tracing disabled
       #
       # @return [Object] Result of the block.
       def self.illegal_call_tracing_disabled(&)
-        Workflow._current.illegal_call_tracing_disabled(&)
+        if Workflow.in_workflow?
+          Workflow._current.illegal_call_tracing_disabled(&)
+        else
+          yield
+        end
       end
 
       # Run a block of code with IO enabled. Specifically this allows the `io_wait` call of the fiber scheduler to work.
       # Users should be cautious about using this as it can often signify unsafe code. Note, this is often only
       # applicable to network code as file IO and most process-based IO does not go through scheduler `io_wait`.
+      #
+      # If this is invoked outside of a workflow, it just runs the block.
       def self.io_enabled(&)
-        Workflow._current.io_enabled(&)
+        if Workflow.in_workflow?
+          Workflow._current.io_enabled(&)
+        else
+          yield
+        end
+      end
+
+      # Run a block of code with the durable/deterministic workflow Fiber scheduler off. This means fallback to default
+      # fiber scheduler and no workflow helpers will be available in the block. This is usually only needed in advanced
+      # situations where a third party library does something like use "Timeout" in a way that shouldn't be made
+      # durable.
+      #
+      # If this is invoked outside of a workflow, it just runs the block.
+      #
+      # This implies {illegal_call_tracing_disabled}.
+      def self.durable_scheduler_disabled(&)
+        if Workflow.in_workflow?
+          Workflow._current.durable_scheduler_disabled(&)
+        else
+          yield
+        end
+      end
+
+      # @!visibility private
+      def self._wrap_ruby_class_as_legal(target_class)
+        Class.new do
+          define_method(:initialize) do |*args, **kwargs, &block|
+            @underlying = Unsafe.illegal_call_tracing_disabled do
+              target_class.new(*args, **kwargs, &block) # steep:ignore
+            end
+          end
+
+          # @!visibility private
+          def method_missing(name, ...)
+            if @underlying.respond_to?(name)
+              # Call with tracing disabled
+              Unsafe.illegal_call_tracing_disabled { @underlying.public_send(name, ...) }
+            else
+              super
+            end
+          end
+
+          # @!visibility private
+          def respond_to_missing?(name, include_all = false)
+            @underlying.respond_to?(name, include_all) || super
+          end
+        end
       end
     end
 
     # 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, :headers
+                    :retry_policy, :memo, :search_attributes, :arg_hints, :headers
 
       # Create a continue as new error.
       #
@@ -534,6 +629,8 @@ module Temporalio
       #   is used.
       # @param search_attributes [SearchAttributes, nil] Search attributes for the workflow. If unset/nil, the current
       #   workflow search attributes are used.
+      # @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.
       # @param headers [Hash<String, Object>] Headers for the workflow. The default is _not_ carried over from the
       #   current workflow.
       def initialize(
@@ -545,6 +642,7 @@ module Temporalio
         retry_policy: nil,
         memo: nil,
         search_attributes: nil,
+        arg_hints: nil,
         headers: {}
       )
         super('Continue as new')
@@ -556,6 +654,7 @@ module Temporalio
         @retry_policy = retry_policy
         @memo = memo
         @search_attributes = search_attributes
+        @arg_hints = arg_hints
         @headers = headers
         Workflow._current.initialize_continue_as_new_error(self)
       end
@@ -571,5 +670,29 @@ module Temporalio
     # error can still be used with configuring workflow failure exception types to change non-deterministic errors from
     # task failures to workflow failures.
     class NondeterminismError < Error; end
+
+    # Mutex is a workflow-safe wrapper around {::Mutex}.
+    #
+    # As of this writing, all methods on Mutex are safe for workflow use and are implicitly made deterministic by the
+    # Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of Mutex by
+    # non-workflow-safe code. However, users may prefer to use the more powerful {wait_condition} approach as a mutex
+    # (e.g. wait until a certain attribute is set to false then set it to true before continuing).
+    Mutex = Unsafe._wrap_ruby_class_as_legal(::Mutex)
+
+    # Queue is a workflow-safe wrapper around {::Queue}.
+    #
+    # As of this writing, all methods on Queue are safe for workflow use and are implicitly made deterministic by the
+    # Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of Queue by
+    # non-workflow-safe code. However, users may prefer to use the more powerful {wait_condition} approach as a queue
+    # (e.g. wait until an array is non-empty before continuing).
+    Queue = Unsafe._wrap_ruby_class_as_legal(::Queue)
+
+    # SizedQueue is a workflow-safe wrapper around {::SizedQueue}.
+    #
+    # As of this writing, all methods on SizedQueue are safe for workflow use and are implicitly made deterministic by
+    # the Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of
+    # SizedQueue by non-workflow-safe code. However, users may prefer to use the more powerful {wait_condition} approach
+    # as a queue (e.g. wait until an array is non-empty before continuing).
+    SizedQueue = Unsafe._wrap_ruby_class_as_legal(::SizedQueue)
   end
 end

data/lib/temporalio.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'temporalio/version'
+require 'temporalio/versioning_override'
 
 # Temporal Ruby SDK. See the README at https://github.com/temporalio/sdk-ruby.
 module Temporalio

data/temporalio.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.extensions = ['ext/Cargo.toml']
   spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.required_ruby_version = '>= 3.2.0'
 
   spec.add_dependency 'google-protobuf', '>= 3.25.0'
   spec.add_dependency 'logger'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: temporalio
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Temporal Technologies Inc
@@ -54,6 +54,7 @@ files:
 - ext/Cargo.toml
 - lib/temporalio.rb
 - lib/temporalio/activity.rb
+- lib/temporalio/activity/cancellation_details.rb
 - lib/temporalio/activity/complete_async_error.rb
 - lib/temporalio/activity/context.rb
 - lib/temporalio/activity/definition.rb
@@ -65,6 +66,7 @@ files:
 - lib/temporalio/api/cloud/cloudservice.rb
 - lib/temporalio/api/cloud/cloudservice/v1/request_response.rb
 - lib/temporalio/api/cloud/cloudservice/v1/service.rb
+- lib/temporalio/api/cloud/connectivityrule/v1/message.rb
 - lib/temporalio/api/cloud/identity/v1/message.rb
 - lib/temporalio/api/cloud/namespace/v1/message.rb
 - lib/temporalio/api/cloud/nexus/v1/message.rb
@@ -105,16 +107,19 @@ files:
 - lib/temporalio/api/protocol/v1/message.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/task_complete_metadata.rb
 - lib/temporalio/api/sdk/v1/user_metadata.rb
+- lib/temporalio/api/sdk/v1/worker_config.rb
 - lib/temporalio/api/sdk/v1/workflow_metadata.rb
 - lib/temporalio/api/taskqueue/v1/message.rb
 - lib/temporalio/api/testservice/v1/request_response.rb
 - lib/temporalio/api/testservice/v1/service.rb
 - lib/temporalio/api/update/v1/message.rb
 - lib/temporalio/api/version/v1/message.rb
+- lib/temporalio/api/worker/v1/message.rb
 - lib/temporalio/api/workflow/v1/message.rb
 - lib/temporalio/api/workflowservice.rb
 - lib/temporalio/api/workflowservice/v1/request_response.rb
@@ -195,6 +200,7 @@ files:
 - lib/temporalio/internal/worker/workflow_instance/scheduler.rb
 - lib/temporalio/internal/worker/workflow_worker.rb
 - lib/temporalio/metric.rb
+- lib/temporalio/priority.rb
 - lib/temporalio/retry_policy.rb
 - lib/temporalio/runtime.rb
 - lib/temporalio/runtime/metric_buffer.rb
@@ -204,16 +210,21 @@ files:
 - lib/temporalio/testing/activity_environment.rb
 - lib/temporalio/testing/workflow_environment.rb
 - lib/temporalio/version.rb
+- lib/temporalio/versioning_override.rb
 - lib/temporalio/worker.rb
 - lib/temporalio/worker/activity_executor.rb
 - lib/temporalio/worker/activity_executor/fiber.rb
 - lib/temporalio/worker/activity_executor/thread_pool.rb
+- lib/temporalio/worker/deployment_options.rb
+- lib/temporalio/worker/illegal_workflow_call_validator.rb
 - lib/temporalio/worker/interceptor.rb
+- lib/temporalio/worker/poller_behavior.rb
 - lib/temporalio/worker/thread_pool.rb
 - lib/temporalio/worker/tuner.rb
 - lib/temporalio/worker/workflow_executor.rb
 - lib/temporalio/worker/workflow_executor/thread_pool.rb
 - lib/temporalio/worker/workflow_replayer.rb
+- lib/temporalio/worker_deployment_version.rb
 - lib/temporalio/workflow.rb
 - lib/temporalio/workflow/activity_cancellation_type.rb
 - lib/temporalio/workflow/child_workflow_cancellation_type.rb
@@ -241,14 +252,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Temporal.io Ruby SDK
 test_files: []