temporalio 0.5.0-x86_64-darwin → 1.0.0-x86_64-darwin

data/lib/temporalio/worker/tuner.rb

@@ -22,10 +22,11 @@ module Temporalio
           end
 
           # @!visibility private
-          def _to_bridge_options
+          def _to_bridge_options(_tuner)
             Internal::Bridge::Worker::TunerSlotSupplierOptions.new(
               fixed_size: slots,
-              resource_based: nil
+              resource_based: nil,
+              custom: nil
             )
           end
         end
@@ -36,7 +37,7 @@ module Temporalio
         class ResourceBased < SlotSupplier
           attr_reader :tuner_options, :slot_options
 
-          # Create a reosurce-based slot supplier.
+          # Create a resource-based slot supplier.
           #
           # @param tuner_options [ResourceBasedTunerOptions] General tuner options.
           # @param slot_options [ResourceBasedSlotOptions] Slot-supplier-specific tuner options.
@@ -46,7 +47,7 @@ module Temporalio
           end
 
           # @!visibility private
-          def _to_bridge_options
+          def _to_bridge_options(_tuner)
             Internal::Bridge::Worker::TunerSlotSupplierOptions.new(
               fixed_size: nil,
               resource_based: Internal::Bridge::Worker::TunerResourceBasedSlotSupplierOptions.new(
@@ -55,14 +56,175 @@ module Temporalio
                 min_slots: slot_options.min_slots,
                 max_slots: slot_options.max_slots,
                 ramp_throttle: slot_options.ramp_throttle
+              ),
+              custom: nil
+            )
+          end
+        end
+
+        # A slot supplier that has callbacks invoked to handle slot supplying.
+        #
+        # Users should be cautious when implementing this and make sure it is heavily tested and the documentation for
+        # every method is well understood.
+        #
+        # @note WARNING: This API is experimental.
+        class Custom < SlotSupplier
+          # Context provided for slot reservation on custom slot supplier.
+          #
+          # @!attribute slot_type
+          #   @return [:workflow, :activity, :local_activity, :nexus] Slot type.
+          # @!attribute task_queue
+          #   @return [String] Task queue.
+          # @!attribute worker_identity
+          #   @return [String] Worker identity.
+          # @!attribute worker_deployment_name
+          #   @return [String] Worker deployment name or empty string if not applicable.
+          # @!attribute worker_build_id
+          #   @return [String] Worker build ID or empty string if not applicable.
+          # @!attribute sticky?
+          #   @return [Boolean] True if this reservation is for a sticky workflow task.
+          ReserveContext = Data.define(
+            :slot_type,
+            :task_queue,
+            :worker_identity,
+            :worker_deployment_name,
+            :worker_build_id,
+            :sticky?
+          )
+
+          # Context provided for marking a slot used.
+          #
+          # @!attribute slot_info
+          #   @return [SlotInfo::Workflow, SlotInfo::Activity, SlotInfo::LocalActivity, SlotInfo::Nexus] Information
+          #     about the slot. This is never nil.
+          # @!attribute permit
+          #   @return [Object] Object that was provided as the permit on reserve.
+          MarkUsedContext = Data.define(
+            :slot_info,
+            :permit
+          )
+
+          # Context provided for releasing a slot.
+          #
+          # @!attribute slot_info
+          #   @return [SlotInfo::Workflow, SlotInfo::Activity, SlotInfo::LocalActivity, SlotInfo::Nexus, nil]
+          #     Information about the slot. This may be nil if the slot was never used.
+          # @!attribute permit
+          #   @return [Object] Object that was provided as the permit on reserve.
+          ReleaseContext = Data.define(
+            :slot_info,
+            :permit
+          )
+
+          # Reserve a slot.
+          #
+          # This can/should block and must provide the permit to the (code) block. The permit is any object (including
+          # nil) that will be given on the context for mark_slot_used and release_slot.
+          #
+          # Just returning from this call is not enough to reserve the slot, a permit must be provided to the block
+          # (e.g. via yield or block.call). If the call completes, the system will still wait on the block (so this can
+          # be backgrounded by passing the block to something else). Reservations may be canceled via the given
+          # cancellation. Users can do things like add_cancel_callback, but it is very important that the code in the
+          # callback is fast as it is run on the same reactor thread as many other Temporal Ruby worker calls.
+          #
+          # @note WARNING: This call should never raise an exception. Any exception raised is ignored and this is called
+          #   again after 1 second.
+          #
+          # @param context [ReserveContext] Contextual information about this reserve call.
+          # @param cancellation [Cancellation] Cancellation that is canceled when the reservation is no longer being
+          #   asked for.
+          # @yield [Object] Confirm reservation and provide a permit.
+          def reserve_slot(context, cancellation, &)
+            raise NotImplementedError
+          end
+
+          # Try to reserve a slot.
+          #
+          # @note WARNING: This should never block, this should return immediately with a permit, or nil if the
+          #   reservation could not occur.
+          #
+          # @note WARNING: This call should never raise an exception. Any exception raised is ignored and the slot
+          #   reservation attempt fails (i.e. same as if this method returned nil).
+          #
+          # @param context [ReserveContext] Contextual information about this reserve call.
+          # @return [Object, nil] A non-nil object to perform the reservation successfully, a nil to fail the
+          #   reservation.
+          def try_reserve_slot(context)
+            raise NotImplementedError
+          end
+
+          # Mark a slot as used.
+          #
+          # Due to the nature of Temporal polling, slots are reserved before they are used and may never get used. This
+          # call is made as just a notification when a slot is actually used.
+          #
+          # @note WARNING: This should never block, this should return immediately.
+          #
+          # @note WARNING: This call should never raise an exception. Any exception raised is ignored.
+          #
+          # @param context [MarkUsedContext] Contextual information about this reserve call.
+          def mark_slot_used(context)
+            raise NotImplementedError
+          end
+
+          # Release a previously reserved slot.
+          #
+          # @note WARNING: This should never block, this should return immediately.
+          #
+          # @note WARNING: This call should never raise an exception. Any exception raised is ignored.
+          #
+          # @param context [ReleaseContext] Contextual information about this reserve call.
+          def release_slot(context)
+            raise NotImplementedError
+          end
+
+          # @!visibility private
+          def _to_bridge_options(tuner)
+            Internal::Bridge::Worker::TunerSlotSupplierOptions.new(
+              fixed_size: nil,
+              resource_based: nil,
+              custom: Internal::Bridge::Worker::CustomSlotSupplier.new(
+                slot_supplier: self,
+                thread_pool: tuner.custom_slot_supplier_thread_pool
               )
             )
           end
+
+          # Slot information.
+          module SlotInfo
+            # Information about a workflow slot.
+            #
+            # @!attribute workflow_type
+            #   @return [String] Workflow type.
+            # @!attribute sticky?
+            #   @return [Boolean] Whether the slot was for a sticky task.
+            Workflow = Data.define(:workflow_type, :sticky?)
+
+            # Information about an activity slot.
+            #
+            # @!attribute activity_type
+            #   @return [String] Activity type.
+            Activity = Data.define(:activity_type)
+
+            # Information about a local activity slot.
+            #
+            # @!attribute activity_type
+            #   @return [String] Activity type.
+            LocalActivity = Data.define(:activity_type)
+
+            # Information about a Nexus slot.
+            #
+            # @!attribute service
+            #   @return [String] Nexus service.
+            # @!attribute operation
+            #   @return [String] Nexus operation.
+            Nexus = Data.define(:service, :operation)
+          end
         end
 
         # @!visibility private
-        def _to_bridge_options
-          raise ArgumentError, 'Tuner slot suppliers must be instances of Fixed or ResourceBased'
+        def _to_bridge_options(_tuner)
+          raise ArgumentError, 'Tuner slot suppliers must be instances of Fixed, ResourceBased, or Custom'
         end
       end
 
@@ -75,10 +237,9 @@ module Temporalio
       # @!attribute target_cpu_usage
       #   @return [Float] A value between 0 and 1 that represents the target (system) CPU usage. This can be set to 1.0
       #     if desired, but it's recommended to leave some headroom for other processes.
-      ResourceBasedTunerOptions = Struct.new(
+      ResourceBasedTunerOptions = Data.define(
         :target_memory_usage,
-        :target_cpu_usage,
-        keyword_init: true
+        :target_cpu_usage
       )
 
       # Options for a specific slot type being used with {SlotSupplier::ResourceBased}.
@@ -94,11 +255,10 @@ module Temporalio
       #
       #     This value matters because how many resources a task will use cannot be determined ahead of time, and thus
       #     the system should wait to see how much resources are used before issuing more slots.
-      ResourceBasedSlotOptions = Struct.new(
+      ResourceBasedSlotOptions = Data.define(
         :min_slots,
         :max_slots,
-        :ramp_throttle,
-        keyword_init: true
+        :ramp_throttle
       )
 
       # Create a fixed-size tuner with the provided number of slots.
@@ -161,27 +321,36 @@ module Temporalio
       # @return [SlotSupplier] Slot supplier for local activities.
       attr_reader :local_activity_slot_supplier
 
+      # @return [ThreadPool, nil] Thread pool for custom slot suppliers.
+      attr_reader :custom_slot_supplier_thread_pool
+
       # Create a tuner from 3 slot suppliers.
       #
       # @param workflow_slot_supplier [SlotSupplier] Slot supplier for workflows.
       # @param activity_slot_supplier [SlotSupplier] Slot supplier for activities.
       # @param local_activity_slot_supplier [SlotSupplier] Slot supplier for local activities.
+      # @param custom_slot_supplier_thread_pool [ThreadPool, nil] Thread pool to make all custom slot supplier calls on.
+      #   If there are no custom slot suppliers, this parameter is ignored. Technically users may set this to nil which
+      #   will not use a thread pool to make slot supplier calls, but that is dangerous and not advised because even the
+      #   slightest blocking call can slow down the system.
       def initialize(
         workflow_slot_supplier:,
         activity_slot_supplier:,
-        local_activity_slot_supplier:
+        local_activity_slot_supplier:,
+        custom_slot_supplier_thread_pool: ThreadPool.default
       )
         @workflow_slot_supplier = workflow_slot_supplier
         @activity_slot_supplier = activity_slot_supplier
         @local_activity_slot_supplier = local_activity_slot_supplier
+        @custom_slot_supplier_thread_pool = custom_slot_supplier_thread_pool
       end
 
       # @!visibility private
       def _to_bridge_options
         Internal::Bridge::Worker::TunerOptions.new(
-          workflow_slot_supplier: workflow_slot_supplier._to_bridge_options,
-          activity_slot_supplier: activity_slot_supplier._to_bridge_options,
-          local_activity_slot_supplier: local_activity_slot_supplier._to_bridge_options
+          workflow_slot_supplier: workflow_slot_supplier._to_bridge_options(self),
+          activity_slot_supplier: activity_slot_supplier._to_bridge_options(self),
+          local_activity_slot_supplier: local_activity_slot_supplier._to_bridge_options(self)
         )
       end
     end

data/lib/temporalio/worker.rb

@@ -267,7 +267,11 @@ module Temporalio
             #:write
           ],
           'Kernel' => %i[abort at_exit autoload autoload? eval exec exit fork gets load open rand readline readlines
-                         spawn srand system test trap],
+                         sleep spawn srand system test trap],
+          # Loggers use mutexes in ways that can hang workflows, so users need to disable the durable scheduler to use
+          # them
+          'Logger' => :all,
+          'Monitor' => :all,
           'Net::HTTP' => :all,
           'Pathname' => :all,
           # TODO(cretz): Investigate why clock_gettime called from Timeout thread affects this code at all. Stack trace
@@ -282,9 +286,14 @@ module Temporalio
           'Signal' => :all,
           'Socket' => :all,
           'Tempfile' => :all,
+          'Timeout' => :all,
           'Thread' => %i[abort_on_exception= exit fork handle_interrupt ignore_deadlock= kill new pass
                          pending_interrupt? report_on_exception= start stop initialize join name= priority= raise run
                          terminate thread_variable_set wakeup],
+          'Thread::ConditionVariable' => :all,
+          'Thread::Mutex' => IllegalWorkflowCallValidator.known_safe_mutex_validator,
+          'Thread::SizedQueue' => :all,
+          'Thread::Queue' => :all,
           'Time' => IllegalWorkflowCallValidator.default_time_validators
         } #: Hash[String, :all | Array[Symbol]]
         hash.each_value(&:freeze)

data/lib/temporalio/workflow/definition.rb

@@ -280,7 +280,7 @@ module Temporalio
         @workflow_update_validators ||= {}
         @defined_methods ||= []
 
-        defn, hash, other_hashes =
+        defn, hash =
           case handler[:type]
           when :init
             raise "workflow_init was applied to #{method_name} instead of initialize" if method_name != :initialize
@@ -306,7 +306,7 @@ module Temporalio
               raw_args: handler[:raw_args],
               unfinished_policy: handler[:unfinished_policy],
               arg_hints: handler[:arg_hints]
-            ), @workflow_signals, [@workflow_queries, @workflow_updates]]
+            ), @workflow_signals]
           when :query
             [Query.new(
               name: handler[:dynamic] ? nil : (handler[:name] || method_name).to_s,
@@ -315,7 +315,7 @@ module Temporalio
               raw_args: handler[:raw_args],
               arg_hints: handler[:arg_hints],
               result_hint: handler[:result_hint]
-            ), @workflow_queries, [@workflow_signals, @workflow_updates]]
+            ), @workflow_queries]
           when :update
             [Update.new(
               name: handler[:dynamic] ? nil : (handler[:name] || method_name).to_s,
@@ -325,7 +325,7 @@ module Temporalio
               unfinished_policy: handler[:unfinished_policy],
               arg_hints: handler[:arg_hints],
               result_hint: handler[:result_hint]
-            ), @workflow_updates, [@workflow_signals, @workflow_queries]]
+            ), @workflow_updates]
           when :dynamic_options
             raise 'Dynamic options method already set' if @dynamic_options_method
 
@@ -341,8 +341,6 @@ module Temporalio
         if other && other.to_invoke != method_name
           raise "Workflow #{handler[:type].name} #{defn.name || '<dynamic>'} defined on " \
                 "different methods #{other.to_invoke} and #{method_name}"
-        elsif defn.name && other_hashes.any? { |h| h.include?(defn.name) }
-          raise "Workflow signal #{defn.name} already defined as a different handler type"
         end
         hash[defn.name] = defn
 

data/lib/temporalio/workflow/info.rb

@@ -7,6 +7,7 @@ module Temporalio
       :continued_run_id,
       :cron_schedule,
       :execution_timeout,
+      :first_execution_run_id,
       :headers,
       :last_failure,
       :last_result,
@@ -35,6 +36,8 @@ module Temporalio
     #   @return [String, nil] Cron schedule if applicable.
     # @!attribute execution_timeout
     #   @return [Float, nil] Execution timeout for the workflow.
+    # @!attribute first_execution_run_id
+    #   @return [String] The very first run ID the workflow ever had, following continuation chains.
     # @!attribute headers
     #   @return [Hash<String, Api::Common::V1::Payload>] Headers.
     # @!attribute last_failure

data/lib/temporalio/workflow.rb

@@ -2,6 +2,7 @@
 
 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'
@@ -207,14 +208,16 @@ module Temporalio
     #
     # @param activity [Class<Activity::Definition>, Symbol, String] Activity definition class or name.
     # @param args [Array<Object>] Arguments to the activity.
+    # @param summary [String, nil] Single-line summary for this activity that may appear in CLI/UI. This can be in
+    #   single-line Temporal markdown format. This is currently experimental.
     # @param schedule_to_close_timeout [Float, nil] Max amount of time the activity can take from first being scheduled
     #   to being completed before it times out. This is inclusive of all retries.
     # @param schedule_to_start_timeout [Float, nil] Max amount of time the activity can take to be started from first
     #   being scheduled.
     # @param start_to_close_timeout [Float, nil] Max amount of time a single activity run can take from when it starts
     #   to when it completes. This is per retry.
-    # @param retry_policy [RetryPolicy] How an activity is retried on failure. If unset, a server-defined default is
-    #   used. Set maximum attempts to 1 to disable retries.
+    # @param retry_policy [RetryPolicy, nil] How an activity is retried on failure. If unset, a default policy is used.
+    #   Set maximum attempts to 1 to disable retries.
     # @param local_retry_threshold [Float, nil] If the activity is retrying and backoff would exceed this value, a timer
     #   is scheduled and the activity is retried after. Otherwise, backoff will happen internally within the task.
     #   Defaults to 1 minute.
@@ -237,6 +240,7 @@ module Temporalio
     def self.execute_local_activity(
       activity,
       *args,
+      summary: nil,
       schedule_to_close_timeout: nil,
       schedule_to_start_timeout: nil,
       start_to_close_timeout: nil,
@@ -250,7 +254,7 @@ module Temporalio
     )
       _current.execute_local_activity(
         activity, *args,
-        schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
+        summary:, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
         retry_policy:, local_retry_threshold:, cancellation:, cancellation_type:,
         activity_id:, arg_hints:, result_hint:
       )
@@ -537,26 +541,72 @@ 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(&)
-        Workflow._current.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
 
@@ -623,5 +673,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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: temporalio
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: x86_64-darwin
 authors:
 - Temporal Technologies Inc
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-07-24 00:00:00.000000000 Z
+date: 2025-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -62,6 +62,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
@@ -107,6 +108,7 @@ files:
 - 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
@@ -154,6 +156,7 @@ files:
 - lib/temporalio/converters/payload_converter/json_plain.rb
 - lib/temporalio/converters/payload_converter/json_protobuf.rb
 - lib/temporalio/converters/raw_value.rb
+- lib/temporalio/env_config.rb
 - lib/temporalio/error.rb
 - lib/temporalio/error/failure.rb
 - lib/temporalio/internal.rb