temporalio 0.1.0 → 0.2.0

data/lib/temporalio/converters/data_converter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/converters/failure_converter'
+require 'temporalio/converters/payload_converter'
+
+module Temporalio
+  module Converters
+    # Data converter for converting/encoding payloads to/from Ruby values.
+    class DataConverter
+      # @return [PayloadConverter] Payload converter. This must be Ractor shareable.
+      attr_reader :payload_converter
+
+      # @return [FailureConverter] Failure converter. This must be Ractor shareable.
+      attr_reader :failure_converter
+
+      # @return [PayloadCodec, nil] Optional codec for encoding/decoding payload bytes such as for encryption.
+      attr_reader :payload_codec
+
+      # @return [DataConverter] Default data converter.
+      def self.default
+        @default ||= DataConverter.new
+      end
+
+      # Create data converter.
+      #
+      # @param payload_converter [PayloadConverter] Payload converter to use. This must be Ractor shareable.
+      # @param failure_converter [FailureConverter] Failure converter to use. This must be Ractor shareable.
+      # @param payload_codec [PayloadCodec, nil] Payload codec to use.
+      def initialize(
+        payload_converter: PayloadConverter.default,
+        failure_converter: FailureConverter.default,
+        payload_codec: nil
+      )
+        raise 'Payload converter not shareable' unless Ractor.shareable?(payload_converter)
+        raise 'Failure converter not shareable' unless Ractor.shareable?(failure_converter)
+
+        @payload_converter = payload_converter
+        @failure_converter = failure_converter
+        @payload_codec = payload_codec
+      end
+
+      # Convert a Ruby value to a payload and encode it.
+      #
+      # @param value [Object] Ruby value.
+      # @return [Api::Common::V1::Payload] Converted and encoded payload.
+      def to_payload(value)
+        payload = payload_converter.to_payload(value)
+        payload = payload_codec.encode([payload]).first if payload_codec
+        payload
+      end
+
+      # Convert multiple Ruby values to a payload set and encode it.
+      #
+      # @param values [Object] Ruby values, converted to array via {::Array}.
+      # @return [Api::Common::V1::Payloads] Converted and encoded payload set.
+      def to_payloads(values)
+        payloads = payload_converter.to_payloads(values)
+        payloads.payloads.replace(payload_codec.encode(payloads.payloads)) if payload_codec && !payloads.payloads.empty?
+        payloads
+      end
+
+      # Decode and convert a payload to a Ruby value.
+      #
+      # @param payload [Api::Common::V1::Payload] Encoded payload.
+      # @return [Object] Decoded and converted Ruby value.
+      def from_payload(payload)
+        payload = payload_codec.decode([payload]).first if payload_codec
+        payload_converter.from_payload(payload)
+      end
+
+      # Decode and convert a payload set to Ruby values.
+      #
+      # @param payloads [Api::Common::V1::Payloads, nil] Encoded payload set.
+      # @return [Array<Object>] Decoded and converted Ruby values.
+      def from_payloads(payloads)
+        return [] unless payloads && !payloads.payloads.empty?
+
+        if payload_codec && !payloads.payloads.empty?
+          payloads = Api::Common::V1::Payloads.new(payloads: payload_codec.decode(payloads.payloads))
+        end
+        payload_converter.from_payloads(payloads)
+      end
+
+      # Convert a Ruby error to a Temporal failure and encode it.
+      #
+      # @param error [Exception] Ruby error.
+      # @return [Api::Failure::V1::Failure] Converted and encoded failure.
+      def to_failure(error)
+        failure_converter.to_failure(error, self)
+      end
+
+      # Decode and convert a Temporal failure to a Ruby error.
+      #
+      # @param failure [Api::Failure::V1::Failure] Encoded failure.
+      # @return [Exception] Decoded and converted Ruby error.
+      def from_failure(failure)
+        failure_converter.from_failure(failure, self)
+      end
+    end
+  end
+end

data/lib/temporalio/converters/failure_converter.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/error'
+require 'temporalio/internal/proto_utils'
+
+module Temporalio
+  module Converters
+    # Base class for converting Ruby errors to/from Temporal failures.
+    class FailureConverter
+      # @return [FailureConverter] Default failure converter.
+      def self.default
+        @default ||= Ractor.make_shareable(FailureConverter.new)
+      end
+
+      # @return [Boolean] If +true+, the message and stack trace of the failure will be moved into the encoded attribute
+      #   section of the failure which can be encoded with a codec.
+      attr_reader :encode_common_attributes
+
+      # Create failure converter.
+      #
+      # @param encode_common_attributes [Boolean] If +true+, the message and stack trace of the failure will be moved
+      #   into the encoded attribute section of the failure which can be encoded with a codec.
+      def initialize(encode_common_attributes: false)
+        @encode_common_attributes = encode_common_attributes
+      end
+
+      # Convert a Ruby error to a Temporal failure.
+      #
+      # @param error [Exception] Ruby error.
+      # @param converter [DataConverter, PayloadConverter] Converter for payloads.
+      # @return [Api::Failure::V1::Failure] Converted failure.
+      def to_failure(error, converter)
+        failure = Api::Failure::V1::Failure.new(
+          message: error.message,
+          stack_trace: error.backtrace&.join("\n")
+        )
+        cause = error.cause
+        failure.cause = to_failure(cause, converter) if cause
+
+        # Convert specific error type details
+        case error
+        when Error::ApplicationError
+          failure.application_failure_info = Api::Failure::V1::ApplicationFailureInfo.new(
+            type: error.type,
+            non_retryable: error.non_retryable,
+            details: converter.to_payloads(error.details),
+            next_retry_delay: Internal::ProtoUtils.seconds_to_duration(error.next_retry_delay)
+          )
+        when Error::TimeoutError
+          failure.timeout_failure_info = Api::Failure::V1::TimeoutFailureInfo.new(
+            timeout_type: error.type,
+            last_heartbeat_details: converter.to_payloads(error.last_heartbeat_details)
+          )
+        when Error::CanceledError
+          failure.canceled_failure_info = Api::Failure::V1::CanceledFailureInfo.new(
+            details: converter.to_payloads(error.details)
+          )
+        when Error::TerminatedError
+          failure.terminated_failure_info = Api::Failure::V1::TerminatedFailureInfo.new
+        when Error::ServerError
+          failure.server_failure_info = Api::Failure::V1::ServerFailureInfo.new(
+            non_retryable: error.non_retryable
+          )
+        when Error::ActivityError
+          failure.activity_failure_info = Api::Failure::V1::ActivityFailureInfo.new(
+            scheduled_event_id: error.scheduled_event_id,
+            started_event_id: error.started_event_id,
+            identity: error.identity,
+            activity_type: Api::Common::V1::ActivityType.new(name: error.activity_type),
+            activity_id: error.activity_id,
+            retry_state: error.retry_state
+          )
+        when Error::ChildWorkflowError
+          failure.child_workflow_execution_failure_info = Api::Failure::V1::ChildWorkflowExecutionFailureInfo.new(
+            namespace: error.namespace,
+            workflow_execution: Api::Common::V1::WorkflowExecution.new(
+              workflow_id: error.workflow_id,
+              run_id: error.run_id
+            ),
+            workflow_type: Api::Common::V1::WorkflowType.new(name: error.workflow_type),
+            initiated_event_id: error.initiated_event_id,
+            started_event_id: error.started_event_id,
+            retry_state: error.retry_state
+          )
+        else
+          failure.application_failure_info = Api::Failure::V1::ApplicationFailureInfo.new(
+            type: error.class.name.split('::').last
+          )
+        end
+
+        # If encoding common attributes, move message and stack trace
+        if @encode_common_attributes
+          failure.encoded_attributes = converter.to_payload(
+            { message: failure.message, stack_trace: failure.stack_trace }
+          )
+          failure.message = 'Encoded failure'
+          failure.stack_trace = ''
+        end
+
+        failure
+      end
+
+      # Convert a Temporal failure to a Ruby error.
+      #
+      # @param failure [Api::Failure::V1::Failure] Failure.
+      # @param converter [DataConverter, PayloadConverter] Converter for payloads.
+      # @return [Error::Failure] Converted Ruby error.
+      def from_failure(failure, converter)
+        # If encoded attributes have any of the fields we expect, try to decode
+        # but ignore any error
+        unless failure.encoded_attributes.nil?
+          begin
+            attrs = converter.from_payload(failure.encoded_attributes)
+            if attrs.is_a?(Hash)
+              # Shallow dup failure here to avoid affecting caller
+              failure = failure.dup
+              failure.message = attrs['message'] if attrs.key?('message')
+              failure.stack_trace = attrs['stack_trace'] if attrs.key?('stack_trace')
+            end
+          rescue StandardError
+            # Ignore failures
+          end
+        end
+
+        # Convert
+        error = if failure.application_failure_info
+                  Error::ApplicationError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Application error'),
+                    *converter.from_payloads(failure.application_failure_info.details),
+                    type: Internal::ProtoUtils.string_or(failure.application_failure_info.type),
+                    non_retryable: failure.application_failure_info.non_retryable,
+                    next_retry_delay: failure.application_failure_info.next_retry_delay&.to_f
+                  )
+                elsif failure.timeout_failure_info
+                  Error::TimeoutError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Timeout'),
+                    type: Internal::ProtoUtils.enum_to_int(Api::Enums::V1::TimeoutType,
+                                                           failure.timeout_failure_info.timeout_type),
+                    last_heartbeat_details: converter.from_payloads(
+                      failure.timeout_failure_info.last_heartbeat_details
+                    )
+                  )
+                elsif failure.canceled_failure_info
+                  Error::CanceledError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Canceled'),
+                    details: converter.from_payloads(failure.canceled_failure_info.details)
+                  )
+                elsif failure.terminated_failure_info
+                  Error::TerminatedError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Terminated'),
+                    details: []
+                  )
+                elsif failure.server_failure_info
+                  Error::ServerError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Server error'),
+                    non_retryable: failure.server_failure_info.non_retryable
+                  )
+                elsif failure.activity_failure_info
+                  Error::ActivityError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Activity error'),
+                    scheduled_event_id: failure.activity_failure_info.scheduled_event_id,
+                    started_event_id: failure.activity_failure_info.started_event_id,
+                    identity: failure.activity_failure_info.identity,
+                    activity_type: failure.activity_failure_info.activity_type.name,
+                    activity_id: failure.activity_failure_info.activity_id,
+                    retry_state: Internal::ProtoUtils.enum_to_int(
+                      Api::Enums::V1::RetryState,
+                      failure.activity_failure_info.retry_state,
+                      zero_means_nil: true
+                    )
+                  )
+                elsif failure.child_workflow_execution_failure_info
+                  Error::ChildWorkflowError.new(
+                    Internal::ProtoUtils.string_or(failure.message, 'Child workflow error'),
+                    namespace: failure.child_workflow_execution_failure_info.namespace,
+                    workflow_id: failure.child_workflow_execution_failure_info.workflow_execution.workflow_id,
+                    run_id: failure.child_workflow_execution_failure_info.workflow_execution.run_id,
+                    workflow_type: failure.child_workflow_execution_failure_info.workflow_type.name,
+                    initiated_event_id: failure.child_workflow_execution_failure_info.initiated_event_id,
+                    started_event_id: failure.child_workflow_execution_failure_info.started_event_id,
+                    retry_state: Internal::ProtoUtils.enum_to_int(
+                      Api::Enums::V1::RetryState,
+                      failure.child_workflow_execution_failure_info.retry_state,
+                      zero_means_nil: true
+                    )
+                  )
+                else
+                  Error::Failure.new(Internal::ProtoUtils.string_or(failure.message, 'Failure error'))
+                end
+
+        Error._with_backtrace_and_cause(
+          error,
+          backtrace: failure.stack_trace.split("\n"),
+          cause: failure.cause ? from_failure(failure.cause, converter) : nil
+        )
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_codec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Converters
+    # Base class for encoding and decoding payloads. Commonly used for encryption.
+    class PayloadCodec
+      # Encode the given payloads into a new set of payloads.
+      #
+      # @param payloads [Enumerable<Api::Common::V1::Payload>] Payloads to encode. This value should not be mutated.
+      # @return [Array<Api::Common::V1::Payload>] Encoded payloads. Note, this does not have to be the same number as
+      #   payloads given, but it must be at least one and cannot be more than was given.
+      def encode(payloads)
+        raise NotImplementedError
+      end
+
+      # Decode the given payloads into a new set of payloads.
+      #
+      # @param payloads [Enumerable<Api::Common::V1::Payload>] Payloads to decode. This value should not be mutated.
+      # @return [Array<Api::Common::V1::Payload>] Decoded payloads. Note, this does not have to be the same number as
+      #   payloads given, but it must be at least one and cannot be more than was given.
+      def decode(payloads)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_converter/binary_null.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/converters/payload_converter/encoding'
+
+module Temporalio
+  module Converters
+    class PayloadConverter
+      # Encoding for +nil+ values for +binary/null+ encoding.
+      class BinaryNull < Encoding
+        ENCODING = 'binary/null'
+
+        # (see Encoding.encoding)
+        def encoding
+          ENCODING
+        end
+
+        # (see Encoding.to_payload)
+        def to_payload(value)
+          return nil unless value.nil?
+
+          Api::Common::V1::Payload.new(
+            metadata: { 'encoding' => ENCODING }
+          )
+        end
+
+        # (see Encoding.from_payload)
+        def from_payload(payload) # rubocop:disable Lint/UnusedMethodArgument
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_converter/binary_plain.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/converters/payload_converter/encoding'
+
+module Temporalio
+  module Converters
+    class PayloadConverter
+      # Encoding for +ASCII_8BIT+ string values for +binary/plain+ encoding.
+      class BinaryPlain < Encoding
+        ENCODING = 'binary/plain'
+
+        # (see Encoding.encoding)
+        def encoding
+          ENCODING
+        end
+
+        # (see Encoding.to_payload)
+        def to_payload(value)
+          return nil unless value.is_a?(String) && value.encoding == ::Encoding::ASCII_8BIT
+
+          Temporalio::Api::Common::V1::Payload.new(
+            metadata: { 'encoding' => ENCODING },
+            data: value
+          )
+        end
+
+        # (see Encoding.from_payload)
+        def from_payload(payload)
+          payload.data
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_converter/binary_protobuf.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'google/protobuf'
+require 'temporalio/api'
+require 'temporalio/converters/payload_converter/encoding'
+
+module Temporalio
+  module Converters
+    class PayloadConverter
+      # Encoding for Protobuf values for +binary/protobuf+ encoding.
+      class BinaryProtobuf < Encoding
+        ENCODING = 'binary/protobuf'
+
+        # (see Encoding.encoding)
+        def encoding
+          ENCODING
+        end
+
+        # (see Encoding.to_payload)
+        def to_payload(value)
+          return nil unless value.is_a?(Google::Protobuf::MessageExts)
+
+          # @type var value: Google::Protobuf::MessageExts
+          Api::Common::V1::Payload.new(
+            metadata: { 'encoding' => ENCODING, 'messageType' => value.class.descriptor.name },
+            data: value.to_proto
+          )
+        end
+
+        # (see Encoding.from_payload)
+        def from_payload(payload)
+          type = payload.metadata['messageType']
+          # @type var desc: untyped
+          desc = Google::Protobuf::DescriptorPool.generated_pool.lookup(type)
+          raise "No protobuf message found in global pool for message type #{type}" unless desc
+
+          desc.msgclass.decode(payload.data)
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_converter/composite.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/converters/payload_converter'
+
+module Temporalio
+  module Converters
+    class PayloadConverter
+      # Payload converter that is a collection of {Encoding}s. When converting to a payload, it tries each encoding
+      # converter in order until one works. The encoding converter is expected to set the +encoding+ metadata which is
+      # then used to match to the proper encoding converter when converting back to a Ruby value.
+      class Composite < PayloadConverter
+        class ConverterNotFound < Error; end
+        class EncodingNotSet < Error; end
+
+        # @return [Hash<String, Encoding>] Encoding converters processed in order.
+        attr_reader :converters
+
+        # Create a payload converter with the given encoding converters processed in order.
+        #
+        # @param converters [Array<Encoding>] Encoding converters.
+        def initialize(*converters)
+          super()
+          @converters = converters.each_with_object({}) do |converter, result|
+            result[converter.encoding] = converter
+            result
+          end
+          @converters.freeze
+        end
+
+        # Convert Ruby value to a payload by going over each encoding converter in order until one can convert.
+        #
+        # @param value [Object] Ruby value to convert.
+        # @return [Api::Common::V1::Payload] Converted payload.
+        # @raise [ConverterNotFound] If no converters can process the value.
+        def to_payload(value)
+          converters.each_value do |converter|
+            payload = converter.to_payload(value)
+            return payload unless payload.nil?
+          end
+          raise ConverterNotFound, "Value of type #{value} has no known converter"
+        end
+
+        # Convert payload to Ruby value based on its +encoding+ metadata on the payload.
+        #
+        # @param payload [Api::Common::V1::Payload] Payload to convert.
+        # @return [Object] Converted Ruby value.
+        # @raise [EncodingNotSet] If encoding not set on the metadata.
+        # @raise [ConverterNotFound] If no converter found for the encoding.
+        def from_payload(payload)
+          encoding = payload.metadata['encoding']
+          raise EncodingNotSet, 'Missing payload encoding' unless encoding
+
+          converter = converters[encoding]
+          raise ConverterNotFound, "No converter for encoding #{encoding}" unless converter
+
+          converter.from_payload(payload)
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_converter/encoding.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Converters
+    class PayloadConverter
+      # Base class for encoding converters that can be used for {Composite} converters. Each converter has an {encoding}
+      # that should be set on the Payload metadata for values it can process. Implementers must implement {encoding}
+      class Encoding
+        # @return [String] Encoding that will be put on the payload metadata if this encoding converter can handle the
+        #   value.
+        def encoding
+          raise NotImplementedError
+        end
+
+        # Convert value to payload if this encoding converter can handle it, or return +nil+. If the converter can
+        # handle it, the resulting payload must have +encoding+ metadata on the payload set to the value of {encoding}.
+        #
+        # @param value [Object] Ruby value to possibly convert.
+        # @return [Api::Common::V1::Payload, nil] Converted payload if it can handle it, +nil+ otherwise.
+        def to_payload(value)
+          raise NotImplementedError
+        end
+
+        # Convert the payload to a Ruby value. The caller confirms the +encoding+ metadata matches {encoding}, so this
+        # will error if it cannot convert.
+        #
+        # @param payload [Api::Common::V1::Payload] Payload to convert.
+        # @return [Object] Converted Ruby value.
+        def from_payload(payload)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_converter/json_plain.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'temporalio/api'
+require 'temporalio/converters/payload_converter/encoding'
+
+module Temporalio
+  module Converters
+    class PayloadConverter
+      # Encoding for all values for +json/plain+ encoding.
+      class JSONPlain < Encoding
+        ENCODING = 'json/plain'
+
+        # Create JSONPlain converter.
+        #
+        # @param parse_options [Hash] Options for {::JSON.parse}.
+        # @param generate_options [Hash] Options for {::JSON.generate}.
+        def initialize(parse_options: { create_additions: true }, generate_options: {})
+          super()
+          @parse_options = parse_options
+          @generate_options = generate_options
+        end
+
+        # (see Encoding.encoding)
+        def encoding
+          ENCODING
+        end
+
+        # (see Encoding.to_payload)
+        def to_payload(value)
+          Api::Common::V1::Payload.new(
+            metadata: { 'encoding' => ENCODING },
+            data: JSON.generate(value, @generate_options).b
+          )
+        end
+
+        # (see Encoding.from_payload)
+        def from_payload(payload)
+          JSON.parse(payload.data, @parse_options)
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/payload_converter/json_protobuf.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'google/protobuf'
+require 'temporalio/api'
+require 'temporalio/converters/payload_converter/encoding'
+
+module Temporalio
+  module Converters
+    class PayloadConverter
+      # Encoding for Protobuf values for +json/protobuf+ encoding.
+      class JSONProtobuf < Encoding
+        ENCODING = 'json/protobuf'
+
+        # (see Encoding.encoding)
+        def encoding
+          ENCODING
+        end
+
+        # (see Encoding.to_payload)
+        def to_payload(value)
+          return nil unless value.is_a?(Google::Protobuf::MessageExts)
+
+          Api::Common::V1::Payload.new(
+            metadata: { 'encoding' => ENCODING, 'messageType' => value.class.descriptor.name },
+            data: value.to_json
+          )
+        end
+
+        # (see Encoding.from_payload)
+        def from_payload(payload)
+          type = payload.metadata['messageType']
+          # @type var desc: untyped
+          desc = Google::Protobuf::DescriptorPool.generated_pool.lookup(type)
+          raise "No protobuf message found in global pool for message type #{type}" unless desc
+
+          desc.msgclass.decode_json(payload.data)
+        end
+      end
+    end
+  end
+end