temporalio 0.1.1 → 0.3.0

data/lib/temporalio/workflow/external_workflow_handle.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+
+module Temporalio
+  module Workflow
+    # Handle for interacting with an external workflow.
+    #
+    # This is created via {Workflow.external_workflow_handle}, it is never instantiated directly.
+    class ExternalWorkflowHandle
+      # @!visibility private
+      def initialize
+        raise NotImplementedError, 'Cannot instantiate an external handle directly'
+      end
+
+      # @return [String] ID for the workflow.
+      def id
+        raise NotImplementedError
+      end
+
+      # @return [String, nil] Run ID for the workflow.
+      def run_id
+        raise NotImplementedError
+      end
+
+      # Signal the external workflow.
+      #
+      # @param signal [Workflow::Definition::Signal, Symbol, String] Signal definition or name.
+      # @param args [Array<Object>] Signal args.
+      # @param cancellation [Cancellation] Cancellation for canceling the signalling.
+      def signal(signal, *args, cancellation: Workflow.cancellation)
+        raise NotImplementedError
+      end
+
+      # Cancel the external workflow.
+      def cancel
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/temporalio/workflow/future.rb

@@ -1,137 +1,150 @@
-module Temporalio
-  class Workflow
-    class Future
-      THREAD_KEY = :temporalio_workflow_future
-
-      class Rejected < StandardError; end
-
-      def self.current
-        Thread.current[THREAD_KEY]
-      end
+# frozen_string_literal: true
 
-      def self.current=(future)
-        Thread.current[THREAD_KEY] = future
-      end
+require 'temporalio/workflow'
 
-      # Revist the reason for combining futures and cancellation scopes, maybe they are separate?
-      def initialize(&block)
-        @resolved = false
-        @value = nil
-        @rejected = false
-        @error = Rejected.new('Future rejected')
-        @cancel_requested = false
-        @blocked_fibers = []
-        @callbacks = []
-        @cancel_callbacks = []
-
-        # Chain cancellation into parent future if one exists
-        Future.current&.on_cancel { cancel }
-
-        # NOTE: resolve and reject methods are accessible via procs to avoid exposing
-        #       them via the public interface.
-        block.call(
-          self,
-          ->(value) { resolve(value) },
-          ->(error) { reject(error) },
-        )
+module Temporalio
+  module Workflow
+    # Asynchronous future for use in workflows to do concurrent and background work. This can only be used inside
+    # workflows.
+    class Future
+      # Return a future that completes when any of the given futures complete. The returned future will return the first
+      # completed futures value or raise the first completed futures exception. To not raise the exception, see
+      # {try_any_of}.
+      #
+      # @param futures [Array<Future<Object>>] Futures to wait for the first to complete.
+      # @return [Future<Object>] Future that relays the first completed future's result/failure.
+      def self.any_of(*futures)
+        Future.new do
+          Workflow.wait_condition(cancellation: nil) { futures.any?(&:done?) }
+          # We know a future is always returned from find, the & just helps type checker
+          (futures.find(&:done?) || raise).wait
+        end
       end
 
-      def then(&block)
-        Future.new do |future, resolve, reject|
-          # @type var wrapped_block: ^() -> void
-          wrapped_block = -> do # rubocop:disable Style/Lambda
-            Fiber.new do
-              Future.current = future
-              # The block is provided the Future on which #then was called
-              result = block.call(self)
-              resolve.call(result)
-            rescue StandardError => e
-              reject.call(e)
-            end.resume
-          end
-
-          if pending?
-            callbacks << wrapped_block
-          else
-            wrapped_block.call
-          end
+      # Return a future that completes when all of the given futures complete or any future fails. The returned future
+      # will return nil on success or raise an exception if any of the futures failed. This means if any future fails,
+      # this will not wait for the other futures to complete. To wait for all futures to complete no matter what, see
+      # {try_all_of}.
+      #
+      # @param futures [Array<Future<Object>>] Futures to wait for all to complete (or first to fail).
+      # @return [Future<nil>] Future that completes successfully with nil when all futures complete, or raises on first
+      #   future failure.
+      def self.all_of(*futures)
+        Future.new do
+          Workflow.wait_condition(cancellation: nil) { futures.all?(&:done?) || futures.any?(&:failure?) }
+          # Raise on error if any
+          futures.find(&:failure?)&.wait
+          nil
         end
       end
 
-      def on_cancel(&block)
-        if pending? && !cancel_requested?
-          cancel_callbacks << block
-        else
-          block.call
+      # Return a future that completes when the first future completes. The result of the future is the future from the
+      # list that completed first. The future returned will never raise even if the first completed future fails.
+      #
+      # @param futures [Array<Future<Object>>] Futures to wait for the first to complete.
+      # @return [Future<Future<Object>>] Future with the first completing future regardless of success/fail.
+      def self.try_any_of(*futures)
+        Future.new do
+          Workflow.wait_condition(cancellation: nil) { futures.any?(&:done?) }
+          futures.find(&:done?) || raise
         end
       end
 
-      def pending?
-        !resolved? && !rejected?
+      # Return a future that completes when all of the given futures complete regardless of success/fail. The returned
+      # future will return nil when all futures are complete.
+      #
+      # @param futures [Array<Future<Object>>] Futures to wait for all to complete (regardless of success/fail).
+      # @return [Future<nil>] Future that completes successfully with nil when all futures complete.
+      def self.try_all_of(*futures)
+        Future.new do
+          Workflow.wait_condition(cancellation: nil) { futures.all?(&:done?) }
+          nil
+        end
       end
 
-      def resolved?
-        @resolved
-      end
+      # @return [Object, nil] Result if the future is done or nil if it is not. This will return nil if the result is
+      #   nil too. Users can use {done?} to differentiate the situations.
+      attr_reader :result
 
-      def rejected?
-        @rejected
-      end
+      # @return [Exception, nil] Failure if this future failed or nil if it didn't or hasn't yet completed.
+      attr_reader :failure
 
-      def await
-        if pending?
-          blocked_fibers << Fiber.current
-          # yield into the parent fiber
-          Fiber.yield while pending?
+      # Create a new future. If created with a block, the block is started in the background and its success/raise is
+      # the result of the future. If created without a block, the result or failure can be set on it.
+      def initialize(&block)
+        @done = false
+        @result = nil
+        @failure = nil
+        @block_given = block_given?
+        return unless block_given?
+
+        @fiber = Fiber.schedule do
+          @result = block.call # steep:ignore
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          @failure = e
+        ensure
+          @done = true
         end
-
-        raise error if rejected?
-
-        value
       end
 
-      def cancel
-        return unless pending?
-        return if cancel_requested?
-
-        @cancel_requested = true
-        cancel_callbacks.each(&:call)
+      # @return [Boolean] True if the future is done, false otherwise.
+      def done?
+        @done
       end
 
-      private
+      # @return [Boolean] True if done and not a failure, false if still running or failed.
+      def result?
+        done? && !failure
+      end
 
-      attr_reader :value, :error, :blocked_fibers, :callbacks, :cancel_callbacks
+      # Mark the future as done and set the result. Does nothing if the future is already done. This cannot be invoked
+      # if the future was constructed with a block.
+      #
+      # @param result [Object] The result, which can be nil.
+      def result=(result)
+        Kernel.raise 'Cannot set result if block given in constructor' if @block_given
+        return if done?
 
-      def cancel_requested?
-        @cancel_requested
+        @result = result
+        @done = true
       end
 
-      # TODO: Run callbacks in a Fiber to allow blocking calls
-      def run_callbacks
-        callbacks.each(&:call)
+      # @return [Boolean] True if done and failed, false if still running or succeeded.
+      def failure?
+        done? && !failure.nil?
       end
 
-      # Unblock every fiber that this future is awaited on
-      def resume_fibers
-        blocked_fibers.each(&:resume)
+      # Mark the future as done and set the failure. Does nothing if the future is already done. This cannot be invoked
+      # if the future was constructed with a block.
+      #
+      # @param failure [Exception] The failure.
+      def failure=(failure)
+        Kernel.raise 'Cannot set result if block given in constructor' if @block_given
+        Kernel.raise 'Cannot set nil failure' if failure.nil?
+        return if done?
+
+        @failure = failure
+        @done = true
       end
 
-      def resolve(value)
-        return unless pending?
+      # Wait on the future to complete. This will return the success or raise the failure. To not raise, use
+      # {wait_no_raise}.
+      #
+      # @return [Object] Result on success.
+      # @raise [Exception] Failure if occurred.
+      def wait
+        Workflow.wait_condition(cancellation: nil) { done? }
+        Kernel.raise failure if failure? # steep:ignore
 
-        @value = value
-        @resolved = true
-        run_callbacks
-        resume_fibers
+        result #: untyped
       end
 
-      def reject(error)
-        return unless pending?
-
-        @error = error
-        @rejected = true
-        run_callbacks
-        resume_fibers
+      # Wait on the future to complete. This will return the success or nil if it failed, this will not raise.
+      #
+      # @return [Object, nil] Result on success or nil on failure.
+      def wait_no_raise
+        Workflow.wait_condition(cancellation: nil) { done? }
+        result
       end
     end
   end

data/lib/temporalio/workflow/handler_unfinished_policy.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Workflow
+    # Actions taken if a workflow completes with running handlers.
+    module HandlerUnfinishedPolicy
+      # Issue a warning in addition to abandoning.
+      WARN_AND_ABANDON = 1
+      # Abandon the handler with no warning.
+      ABANDON = 2
+    end
+  end
+end

data/lib/temporalio/workflow/info.rb

@@ -1,76 +1,82 @@
-module Temporalio
-  class Workflow
-    # Class containing information about a workflow's parent.
-    class ParentInfo < Struct.new(
-      :namespace,
-      :run_id,
-      :workflow_id,
-      keyword_init: true,
-    )
-      # @!attribute [r] namespace
-      #   @return [String] Namespace of the parent workflow.
-      # @!attribute [r] run_id
-      #   @return [String] Run ID of the parent workflow.
-      # @!attribute [r] workflow_id
-      #   @return [String] ID of the parent workflow.
-    end
+# frozen_string_literal: true
 
-    # Class containing information about a workflow.
-    class Info < Struct.new(
+module Temporalio
+  module Workflow
+    Info = Struct.new(
       :attempt,
       :continued_run_id,
       :cron_schedule,
       :execution_timeout,
-      :headers,
+      :last_failure,
+      :last_result,
       :namespace,
       :parent,
-      :raw_memo,
       :retry_policy,
       :run_id,
       :run_timeout,
-      :search_attributes,
       :start_time,
       :task_queue,
       :task_timeout,
       :workflow_id,
       :workflow_type,
-      keyword_init: true,
+      keyword_init: true
     )
-      # @!attribute [r] attempt
-      #   @return [Integer] Attempt of executing the workflow.
-      # @!attribute [r] continued_run_id
-      #   @return [String] Run id of the previous workflow which continued-as-new or retired or cron
-      #     executed into this workflow, if any.
-      # @!attribute [r] cron_schedule
-      #   @return [String] Cron schedule of the workflow.
-      # @!attribute [r] execution_timeout
-      #   @return [Float] Execution timeout of the workflow (in seconds).
-      # @!attribute [r] headers
-      #   @return [Hash<String, any>] Headers for the workflow.
-      # @!attribute [r] namespace
-      #   @return [String] Namespace of the workflow.
-      # @!attribute [r] parent
-      #   @return [Temporalio::Workflow::ParentInfo] Info of the parent workflow.
-      # @!attribute [r] raw_memo
-      #   @return [Hash<String, any>] Memo for the workflow.
-      # @!attribute [r] retry_policy
-      #   @return [Temporalio::RetryPolicy] RetryPolicy of the workflow.
-      # @!attribute [r] run_id
-      #   @return [String] Run ID of the workflow.
-      # @!attribute [r] run_timeout
-      #   @return [Float] Run timeout of the workflow (in seconds).
-      # @!attribute [r] search_attributes
-      #   @return [Hash<String, String>] Search attributes of the workflow.
-      # @!attribute [r] start_time
-      #   @return [Time] Start time of the workflow.
-      # @!attribute [r] task_queue
-      #   @return [String] Task queue of the workflow.
-      # @!attribute [r] task_timeout
-      #   @return [Float] Task timeout of the workflow (in seconds).
-      # @!attribute [r] workflow_id
-      #   @return [String] ID of the workflow.
-      # @!attribute [r] workflow_type
-      #   @return [String] Type of the workflow.
+
+    # Information about the running workflow. This is immutable for the life of the workflow run.
+    #
+    # @!attribute attempt
+    #   @return [Integer] Current workflow attempt.
+    # @!attribute continued_run_id
+    #   @return [String, nil] Run ID if this was continued.
+    # @!attribute cron_schedule
+    #   @return [String, nil] Cron schedule if applicable.
+    # @!attribute execution_timeout
+    #   @return [Float, nil] Execution timeout for the workflow.
+    # @!attribute last_failure
+    #   @return [Exception, nil] Failure if this workflow run is a continuation of a failure.
+    # @!attribute last_result
+    #   @return [Object, nil] Successful result if this workflow is a continuation of a success.
+    # @!attribute namespace
+    #   @return [String] Namespace for the workflow.
+    # @!attribute parent
+    #   @return [ParentInfo, nil] Parent information for the workflow if this is a child.
+    # @!attribute retry_policy
+    #   @return [RetryPolicy, nil] Retry policy for the workflow.
+    # @!attribute run_id
+    #   @return [String] Run ID for the workflow.
+    # @!attribute run_timeout
+    #   @return [Float, nil] Run timeout for the workflow.
+    # @!attribute start_time
+    #   @return [Time] Time when the workflow started.
+    # @!attribute task_queue
+    #   @return [String] Task queue for the workflow.
+    # @!attribute task_timeout
+    #   @return [Float] Task timeout for the workflow.
+    # @!attribute workflow_id
+    #   @return [String] ID for the workflow.
+    # @!attribute workflow_type
+    #   @return [String] Workflow type name.
+    #
+    # @note WARNING: This class may have required parameters added to its constructor. Users should not instantiate this
+    #   class or it may break in incompatible ways.
+    class Info
+      # Information about a parent of a workflow.
+      #
+      # @!attribute namespace
+      #   @return [String] Namespace for the parent.
+      # @!attribute run_id
+      #   @return [String] Run ID for the parent.
+      # @!attribute workflow_id
+      #   @return [String] Workflow ID for the parent.
+      #
+      # @note WARNING: This class may have required parameters added to its constructor. Users should not instantiate
+      #   this class or it may break in incompatible ways.
+      ParentInfo = Struct.new(
+        :namespace,
+        :run_id,
+        :workflow_id,
+        keyword_init: true
+      )
     end
   end
 end

data/lib/temporalio/workflow/parent_close_policy.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/bridge/api'
+
+module Temporalio
+  module Workflow
+    # How a child workflow should be handled when the parent closes.
+    module ParentClosePolicy
+      # Unset.
+      UNSPECIFIED = Internal::Bridge::Api::ChildWorkflow::ParentClosePolicy::PARENT_CLOSE_POLICY_UNSPECIFIED
+      # The child workflow will also terminate.
+      TERMINATE = Internal::Bridge::Api::ChildWorkflow::ParentClosePolicy::PARENT_CLOSE_POLICY_TERMINATE
+      # The child workflow will do nothing.
+      ABANDON = Internal::Bridge::Api::ChildWorkflow::ParentClosePolicy::PARENT_CLOSE_POLICY_ABANDON
+      # Cancellation will be requested of the child workflow.
+      REQUEST_CANCEL = Internal::Bridge::Api::ChildWorkflow::ParentClosePolicy::PARENT_CLOSE_POLICY_REQUEST_CANCEL
+    end
+  end
+end

data/lib/temporalio/workflow/update_info.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Workflow
+    # Information about a workflow update
+    #
+    # @!attribute id
+    #   @return [String] Update ID.
+    # @!attribute name
+    #   @return [String] Update name.
+    #
+    # @note WARNING: This class may have required parameters added to its constructor. Users should not instantiate this
+    #   class or it may break in incompatible ways.
+    UpdateInfo = Struct.new(
+      :id,
+      :name,
+      keyword_init: true
+    )
+  end
+end