temporalio 0.3.0 → 0.5.0

data/lib/temporalio/workflow.rb

@@ -2,6 +2,7 @@
 
 require 'random/formatter'
 require 'temporalio/error'
+require 'temporalio/priority'
 require 'temporalio/workflow/activity_cancellation_type'
 require 'temporalio/workflow/child_workflow_cancellation_type'
 require 'temporalio/workflow/child_workflow_handle'
@@ -38,6 +39,36 @@ module Temporalio
       _current.continue_as_new_suggested
     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.
+    #
+    # @return [String] Current details. Default is empty string.
+    def self.current_details
+      _current.current_details
+    end
+
+    # Set 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.
+    #
+    # @param details [String] Current details. Can use empty string to unset.
+    def self.current_details=(details)
+      _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
@@ -77,6 +108,8 @@ module Temporalio
     # @param activity [Class<Activity::Definition>, Symbol, String] Activity definition class or activity name.
     # @param args [Array<Object>] Arguments to the activity.
     # @param task_queue [String] Task queue to run the activity on. Defaults to the current workflow's task queue.
+    # @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
@@ -98,6 +131,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).
@@ -107,6 +145,7 @@ module Temporalio
       activity,
       *args,
       task_queue: info.task_queue,
+      summary: nil,
       schedule_to_close_timeout: nil,
       schedule_to_start_timeout: nil,
       start_to_close_timeout: nil,
@@ -115,12 +154,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:, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
-        heartbeat_timeout:, retry_policy:, cancellation:, cancellation_type:, activity_id:, disable_eager_execution:
+        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:,
+        priority:, arg_hints:, result_hint:
       )
     end
 
@@ -130,6 +173,8 @@ module Temporalio
       *args,
       id: random.uuid,
       task_queue: info.task_queue,
+      static_summary: nil,
+      static_details: nil,
       cancellation: Workflow.cancellation,
       cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED,
       parent_close_policy: ParentClosePolicy::TERMINATE,
@@ -140,12 +185,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:, cancellation:, cancellation_type:, parent_close_policy:, execution_timeout:, run_timeout:,
-        task_timeout:, id_reuse_policy:, retry_policy:, cron_schedule:, memo:, search_attributes:
+        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:, priority:, arg_hints:, result_hint:
       ).result
     end
 
@@ -176,6 +225,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).
@@ -191,12 +244,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
 
@@ -220,6 +276,12 @@ module Temporalio
       _current.info
     end
 
+    # @return [Definition, nil] Workflow class instance. This should always be present except in
+    #   {Worker::Interceptor::Workflow::Inbound.init} where it will be nil.
+    def self.instance
+      _current.instance
+    end
+
     # @return [Logger] Logger for the workflow. This is a scoped logger that automatically appends workflow details to
     #   every log and takes care not to log during replay.
     def self.logger
@@ -298,7 +360,7 @@ module Temporalio
     #   value cannot be negative. Since Temporal timers are server-side, timer resolution may not end up as precise as
     #   system timers.
     # @param summary [String, nil] A simple string identifying this timer that may be visible in UI/CLI. While it can be
-    #   normal text, it is best to treat as a timer ID.
+    #   normal text, it is best to treat as a timer ID. This is currently experimental.
     # @param cancellation [Cancellation] Cancellation for this timer.
     # @raise [Error::CanceledError] Sleep canceled.
     def self.sleep(duration, summary: nil, cancellation: Workflow.cancellation)
@@ -311,6 +373,12 @@ module Temporalio
     # @param args [Array<Object>] Arguments to the workflow.
     # @param id [String] Unique identifier for the workflow execution. Defaults to a new UUID from {random}.
     # @param task_queue [String] Task queue to run the workflow on. Defaults to the current workflow's task queue.
+    # @param static_summary [String, nil] Fixed single-line summary for this workflow execution that may appear in
+    #   CLI/UI. This can be in single-line Temporal markdown format. This is currently experimental.
+    # @param static_details [String, nil] Fixed details for this workflow execution that may appear in CLI/UI. This can
+    #   be in Temporal markdown format and can be multiple lines. This is a fixed value on the workflow that cannot be
+    #   updated. For details that can be updated, use {Workflow.current_details=} within the workflow. This is currently
+    #   experimental.
     # @param cancellation [Cancellation] Cancellation to apply to the child workflow. How cancellation is treated is
     #   based on `cancellation_type`. This defaults to the workflow's cancellation.
     # @param cancellation_type [ChildWorkflowCancellationType] How the child workflow will react to cancellation.
@@ -324,6 +392,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.
@@ -333,6 +406,8 @@ module Temporalio
       *args,
       id: random.uuid,
       task_queue: info.task_queue,
+      static_summary: nil,
+      static_details: nil,
       cancellation: Workflow.cancellation,
       cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED,
       parent_close_policy: ParentClosePolicy::TERMINATE,
@@ -343,15 +418,25 @@ 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:, cancellation:, cancellation_type:, parent_close_policy:, execution_timeout:, run_timeout:,
-        task_timeout:, id_reuse_policy:, retry_policy:, cron_schedule:, memo:, search_attributes:
+        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:, priority:, arg_hints:, result_hint:
       )
     end
 
+    # @return [Hash<Object, Object>] General in-workflow storage. Most users will store state on the workflow class
+    #   instance instead, this is only for utilities without access to the class instance.
+    def self.storage
+      _current.storage
+    end
+
     # Run the block until the timeout is reached. This is backed by {sleep}. This does not accept cancellation because
     # it is expected the block within will properly handle/bubble cancellation.
     #
@@ -361,8 +446,8 @@ module Temporalio
     #   exception.
     # @param message [String] Message to use for timeout exception. Defaults to "execution expired" like
     #   {::Timeout.timeout}.
-    # @param summary [String] Timer summer for the timer created by this timeout. This is backed by {sleep} so see that
-    #   method for details.
+    # @param summary [String] Timer summary for the timer created by this timeout. This is backed by {sleep} so see that
+    #   method for details. This is currently experimental.
     #
     # @yield Block to run with a timeout.
     # @return [Object] The result of the block.
@@ -458,12 +543,27 @@ module Temporalio
       def self.illegal_call_tracing_disabled(&)
         Workflow._current.illegal_call_tracing_disabled(&)
       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`.
+      def self.io_enabled(&)
+        Workflow._current.io_enabled(&)
+      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.
+      def self.durable_scheduler_disabled(&)
+        Workflow._current.durable_scheduler_disabled(&)
+      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.
       #
@@ -482,6 +582,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(
@@ -493,6 +595,7 @@ module Temporalio
         retry_policy: nil,
         memo: nil,
         search_attributes: nil,
+        arg_hints: nil,
         headers: {}
       )
         super('Continue as new')
@@ -504,6 +607,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

data/lib/temporalio/workflow_history.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
+require 'temporalio/api'
+
 module Temporalio
   # Representation of a workflow's history.
   class WorkflowHistory
-    # History events for the workflow.
+    # Convert a JSON string to workflow history. This supports the JSON format exported by Temporal UI and CLI.
+    #
+    # @param json [String] JSON string.
+    # @return [WorkflowHistory] Converted history.
+    def self.from_history_json(json)
+      WorkflowHistory.new(Api::History::V1::History.decode_json(json).events.to_a)
+    end
+
+    # @return [Array<Api::History::V1::HistoryEvent>] History events for the workflow.
     attr_reader :events
 
     # @!visibility private
@@ -18,5 +28,20 @@ module Temporalio
 
       start.workflow_id
     end
+
+    # Convert to history JSON.
+    #
+    # @return [String] JSON string.
+    def to_history_json
+      Api::History::V1::History.encode_json(Api::History::V1::History.new(events:))
+    end
+
+    # Compare history.
+    #
+    # @param other [WorkflowHistory] Other history.
+    # @return [Boolean] True if equal.
+    def ==(other)
+      other.is_a?(WorkflowHistory) && events == other.events
+    end
   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,8 @@ 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.27.0'
+  spec.add_dependency 'google-protobuf', '>= 3.25.0'
+  spec.add_dependency 'logger'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: temporalio
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Temporal Technologies Inc
 bindir: exe
 cert_chain: []
-date: 2025-01-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -15,14 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.27.0
+        version: 3.25.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.27.0
+        version: 3.25.0
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - sdk@temporal.io
 executables: []
@@ -40,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
@@ -62,12 +77,15 @@ 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/deployment/v1/message.rb
 - lib/temporalio/api/enums/v1/batch_operation.rb
 - lib/temporalio/api/enums/v1/command_type.rb
 - lib/temporalio/api/enums/v1/common.rb
+- lib/temporalio/api/enums/v1/deployment.rb
 - lib/temporalio/api/enums/v1/event_type.rb
 - lib/temporalio/api/enums/v1/failed_cause.rb
 - lib/temporalio/api/enums/v1/namespace.rb
+- lib/temporalio/api/enums/v1/nexus.rb
 - lib/temporalio/api/enums/v1/query.rb
 - lib/temporalio/api/enums/v1/reset.rb
 - lib/temporalio/api/enums/v1/schedule.rb
@@ -88,6 +106,7 @@ 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
@@ -98,6 +117,7 @@ files:
 - 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
@@ -115,6 +135,7 @@ files:
 - lib/temporalio/client/interceptor.rb
 - lib/temporalio/client/schedule.rb
 - lib/temporalio/client/schedule_handle.rb
+- lib/temporalio/client/with_start_workflow_operation.rb
 - lib/temporalio/client/workflow_execution.rb
 - lib/temporalio/client/workflow_execution_count.rb
 - lib/temporalio/client/workflow_execution_status.rb
@@ -123,6 +144,7 @@ files:
 - lib/temporalio/client/workflow_update_handle.rb
 - lib/temporalio/client/workflow_update_wait_stage.rb
 - lib/temporalio/common_enums.rb
+- lib/temporalio/contrib/open_telemetry.rb
 - lib/temporalio/converters.rb
 - lib/temporalio/converters/data_converter.rb
 - lib/temporalio/converters/failure_converter.rb
@@ -176,23 +198,31 @@ 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
 - lib/temporalio/scoped_logger.rb
 - lib/temporalio/search_attributes.rb
 - lib/temporalio/testing.rb
 - 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
@@ -220,14 +250,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.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Temporal.io Ruby SDK
 test_files: []