temporalio 0.1.1 → 0.2.0

data/lib/temporalio/runtime.rb

@@ -1,25 +1,271 @@
-require 'singleton'
-require 'temporalio/bridge'
-require 'temporalio/worker/reactor'
+# frozen_string_literal: true
+
+require 'temporalio/internal/bridge/runtime'
 
 module Temporalio
-  # @api private
+  # Runtime for Temporal Ruby SDK.
+  #
+  # Only one global {Runtime} needs to exist. Users are encouraged to use {default}. To configure it, create a runtime
+  # before any clients are created, and set it via {default=}. Every time a new runtime is created, a new internal Rust
+  # thread pool is created.
   class Runtime
-    include Singleton
+    # Telemetry options for the runtime.
+    #
+    # @!attribute logging
+    #   @return [LoggingOptions, nil] Logging options, default is new {LoggingOptions} with no parameters. Can be set
+    #     to nil to disable logging.
+    # @!attribute metrics
+    #   @return [MetricsOptions, nil] Metrics options.
+    TelemetryOptions = Struct.new(
+      :logging,
+      :metrics,
+      keyword_init: true
+    ) do
+      # @!visibility private
+      def initialize(**kwargs)
+        # @type var kwargs: untyped
+        kwargs[:logging] = LoggingOptions.new unless kwargs.key?(:logging)
+        super
+      end
+
+      # @!visibility private
+      def _to_bridge
+        # @type self: TelemetryOptions
+        Internal::Bridge::Runtime::TelemetryOptions.new(
+          logging: logging&._to_bridge,
+          metrics: metrics&._to_bridge
+        )
+      end
+    end
+
+    # Logging options for runtime telemetry.
+    #
+    # @!attribute log_filter
+    #   @return [LoggingFilterOptions, String] Logging filter for Core, default is new {LoggingFilterOptions} with no
+    #     parameters.
+    LoggingOptions = Struct.new(
+      :log_filter,
+      # TODO(cretz): forward_to
+      keyword_init: true
+    ) do
+      # @!visibility private
+      def initialize(**kwargs)
+        # @type var kwargs: untyped
+        kwargs[:log_filter] = LoggingFilterOptions.new unless kwargs.key?(:log_filter)
+        super
+      end
+
+      # @!visibility private
+      def _to_bridge
+        # @type self: LoggingOptions
+        Internal::Bridge::Runtime::LoggingOptions.new(
+          log_filter: if log_filter.is_a?(String)
+                        log_filter
+                      elsif log_filter.is_a?(LoggingFilterOptions)
+                        log_filter._to_bridge
+                      else
+                        raise 'Log filter must be string or LoggingFilterOptions'
+                      end
+        )
+      end
+    end
 
-    attr_reader :core_runtime, :reactor
+    # Logging filter options for Core.
+    #
+    # @!attribute core_level
+    #   @return ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'] Log level for Core log messages, default is +'WARN'+.
+    # @!attribute other_level
+    #   @return ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'] Log level for other Rust log messages, default is +'WARN'+.
+    LoggingFilterOptions = Struct.new(
+      :core_level,
+      :other_level,
+      keyword_init: true
+    ) do
+      # @!visibility private
+      def initialize(**kwargs)
+        # @type var kwargs: untyped
+        kwargs[:core_level] = 'WARN' unless kwargs.key?(:core_level)
+        kwargs[:other_level] = 'ERROR' unless kwargs.key?(:other_level)
+        super
+      end
 
-    def initialize
-      @core_runtime = Temporalio::Bridge::Runtime.init
-      @reactor = Temporalio::Worker::Reactor.new
+      # @!visibility private
+      def _to_bridge
+        # @type self: LoggingFilterOptions
+        "#{other_level},temporal_sdk_core=#{core_level},temporal_client=#{core_level},temporal_sdk=#{core_level}"
+      end
     end
 
-    def ensure_callback_loop
-      return if @thread
+    # Metrics options for runtime telemetry. Either {opentelemetry} or {prometheus} required, but not both.
+    #
+    # @!attribute opentelemetry
+    #   @return [OpenTelemetryMetricsOptions, nil] OpenTelemetry options if using OpenTelemetry. This is mutually
+    #     exclusive with +prometheus+.
+    # @!attribute prometheus
+    #   @return [PrometheusMetricsOptions, nil] Prometheus options if using Prometheus. This is mutually exclusive with
+    #     +opentelemetry+.
+    # @!attribute attach_service_name
+    #   @return [Boolean] Whether to put the service_name on every metric, default +true+.
+    # @!attribute global_tags
+    #   @return [Hash<String, String>, nil] Resource tags to be applied to all metrics.
+    # @!attribute metric_prefix
+    #   @return [String, nil] Prefix to put on every Temporal metric. If unset, defaults to +temporal_+.
+    MetricsOptions = Struct.new(
+      :opentelemetry,
+      :prometheus,
+      :attach_service_name,
+      :global_tags,
+      :metric_prefix,
+      keyword_init: true
+    ) do
+      # @!visibility private
+      def initialize(**kwargs)
+        # @type var kwargs: untyped
+        kwargs[:attach_service_name] = true unless kwargs.key?(:attach_service_name)
+        super
+      end
+
+      # @!visibility private
+      def _to_bridge
+        # @type self: MetricsOptions
+        Internal::Bridge::Runtime::MetricsOptions.new(
+          opentelemetry: opentelemetry&._to_bridge,
+          prometheus: prometheus&._to_bridge,
+          attach_service_name:,
+          global_tags:,
+          metric_prefix:
+        )
+      end
+    end
+
+    # Options for exporting metrics to OpenTelemetry.
+    #
+    # @!attribute url
+    #   @return [String] URL for OpenTelemetry endpoint.
+    # @!attribute headers
+    #   @return [Hash<String, String>, nil] Headers for OpenTelemetry endpoint.
+    # @!attribute metric_periodicity
+    #   @return [Float, nil] How frequently metrics should be exported, unset uses internal default.
+    # @!attribute metric_temporality
+    #   @return [MetricTemporality] How frequently metrics should be exported, default is
+    #     {MetricTemporality::CUMULATIVE}.
+    # @!attribute durations_as_seconds
+    #   @return [Boolean] Whether to use float seconds instead of integer milliseconds for durations, default is
+    #     +false+.
+    OpenTelemetryMetricsOptions = Struct.new(
+      :url,
+      :headers,
+      :metric_periodicity,
+      :metric_temporality,
+      :durations_as_seconds,
+      keyword_init: true
+    ) do
+      # OpenTelemetry metric temporality.
+      module MetricTemporality # rubocop:disable Lint/ConstantDefinitionInBlock
+        CUMULATIVE = 1
+        DELTA = 2
+      end
 
-      @thread = Thread.new do
-        core_runtime.run_callback_loop
+      # @!visibility private
+      def initialize(**kwargs)
+        # @type var kwargs: untyped
+        kwargs[:metric_temporality] = MetricTemporality::CUMULATIVE unless kwargs.key?(:metric_temporality)
+        kwargs[:durations_as_seconds] = false unless kwargs.key?(:durations_as_seconds)
+        super
       end
+
+      # @!visibility private
+      def _to_bridge
+        # @type self: OpenTelemetryMetricsOptions
+        Internal::Bridge::Runtime::OpenTelemetryMetricsOptions.new(
+          url:,
+          headers:,
+          metric_periodicity:,
+          metric_temporality_delta: case metric_temporality
+                                    when MetricTemporality::CUMULATIVE then false
+                                    when MetricTemporality::DELTA then true
+                                    else raise 'Unrecognized metric temporality'
+                                    end,
+          durations_as_seconds:
+        )
+      end
+    end
+
+    # Options for exporting metrics to Prometheus.
+    #
+    # @!attribute bind_address
+    #   @return [String] Address to bind to for Prometheus endpoint.
+    # @!attribute counters_total_suffix
+    #   @return [Boolean] If +true+, all counters will include a +_total+ suffix, default is +false+.
+    # @!attribute unit_suffix
+    #   @return [Boolean] If +true+, all histograms will include the unit in their name as a suffix, default is +false+.
+    # @!attribute durations_as_seconds
+    #   @return [Boolean] Whether to use float seconds instead of integer milliseconds for durations, default is
+    #     +false+.
+    PrometheusMetricsOptions = Struct.new(
+      :bind_address,
+      :counters_total_suffix,
+      :unit_suffix,
+      :durations_as_seconds,
+      keyword_init: true
+    ) do
+      # @!visibility private
+      def initialize(**kwargs)
+        # @type var kwargs: untyped
+        kwargs[:counters_total_suffix] = false unless kwargs.key?(:counters_total_suffix)
+        kwargs[:unit_suffix] = false unless kwargs.key?(:unit_suffix)
+        kwargs[:durations_as_seconds] = false unless kwargs.key?(:durations_as_seconds)
+        super
+      end
+
+      # @!visibility private
+      def _to_bridge
+        # @type self: PrometheusMetricsOptions
+        Internal::Bridge::Runtime::PrometheusMetricsOptions.new(
+          bind_address:,
+          counters_total_suffix:,
+          unit_suffix:,
+          durations_as_seconds:
+        )
+      end
+    end
+
+    # Default runtime, lazily created upon first access. If needing a different default, make sure it is updated via
+    # {default=} before this is called (either directly or as a parameter to something like {Client}).
+    #
+    # @return [Runtime] Default runtime.
+    def self.default
+      @default ||= Runtime.new
+    end
+
+    # Set the default runtime. Must be called before {default} accessed.
+    #
+    # @param runtime [Runtime] Runtime to set as default.
+    # @raise If default has already been accessed.
+    def self.default=(runtime)
+      raise 'Runtime already set or requested' unless @default.nil?
+
+      @default = runtime
+    end
+
+    # Create new Runtime. For most users, this should only be done once globally. In addition to creating a Rust thread
+    # pool, this also consumes a Ruby thread for its lifetime.
+    #
+    # @param telemetry [TelemetryOptions] Telemetry options to set.
+    def initialize(telemetry: TelemetryOptions.new)
+      @core_runtime = Internal::Bridge::Runtime.new(
+        Internal::Bridge::Runtime::Options.new(telemetry: telemetry._to_bridge)
+      )
+      # We need a thread to run the command loop
+      # TODO(cretz): Is this something users should be concerned about or need control over?
+      Thread.new do
+        @core_runtime.run_command_loop
+      end
+    end
+
+    # @!visibility private
+    def _core_runtime
+      @core_runtime
     end
   end
 end

data/lib/temporalio/scoped_logger.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'logger'
+
+module Temporalio
+  # Implementation via delegator to {::Logger} that puts scoped values on the log message and appends them to the log
+  # message.
+  class ScopedLogger < SimpleDelegator
+    # @!attribute scoped_values_getter
+    #   @return [Proc, nil] Proc to call to get scoped values when needed.
+    attr_accessor :scoped_values_getter
+
+    # @!attribute scoped_values_getter
+    #   @return [Boolean] Whether the scoped value appending is disabled.
+    attr_accessor :disable_scoped_values
+
+    # @see Logger.add
+    def add(severity, message = nil, progname = nil)
+      return true if (severity || Logger::Unknown) < level
+      return super if scoped_values_getter.nil? || @disable_scoped_values
+
+      scoped_values = scoped_values_getter.call
+      return super if scoped_values.nil?
+
+      if message.nil?
+        if block_given?
+          message = yield
+        else
+          message = progname
+          progname = nil
+        end
+      end
+      # For exceptions we need to dup and append here, for everything else we
+      # need to delegate to a log message
+      new_message = if message.is_a?(Exception)
+                      message.exception("#{message.message} #{scoped_values}")
+                    else
+                      LogMessage.new(message, scoped_values)
+                    end
+      super(severity, new_message, progname)
+    end
+    alias log add
+
+    # @see Logger.debug
+    def debug(progname = nil, &)
+      add(Logger::DEBUG, nil, progname, &)
+    end
+
+    # @see Logger.info
+    def info(progname = nil, &)
+      add(Logger::INFO, nil, progname, &)
+    end
+
+    # @see Logger.warn
+    def warn(progname = nil, &)
+      add(Logger::WARN, nil, progname, &)
+    end
+
+    # @see Logger.error
+    def error(progname = nil, &)
+      add(Logger::ERROR, nil, progname, &)
+    end
+
+    # @see Logger.fatal
+    def fatal(progname = nil, &)
+      add(Logger::FATAL, nil, progname, &)
+    end
+
+    # @see Logger.unknown
+    def unknown(progname = nil, &)
+      add(Logger::UNKNOWN, nil, progname, &)
+    end
+
+    # Scoped log message wrapping original log message.
+    class LogMessage
+      # @return [Object] Original log message.
+      attr_reader :message
+
+      # @return [Object] Scoped values.
+      attr_reader :scoped_values
+
+      # @!visibility private
+      def initialize(message, scoped_values)
+        @message = message
+        @scoped_values = scoped_values
+      end
+
+      # @return [String] Message with scoped values appended.
+      def inspect
+        message_str = message.is_a?(String) ? message : message.inspect
+        "#{message_str} #{scoped_values}"
+      end
+    end
+  end
+end

data/lib/temporalio/search_attributes.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+
+module Temporalio
+  # Collection of typed search attributes.
+  #
+  # This is represented as a mapping of {SearchAttributes::Key} to object values. This is not a hash though it does have
+  # a few hash-like methods and can be converted to a hash via {#to_h}. In some situations, such as in workflows, this
+  # class is frozen.
+  class SearchAttributes
+    # Key for a search attribute.
+    class Key
+      # @return [String] Name of the search attribute.
+      attr_reader :name
+
+      # @return [IndexedValueType] Type of the search attribute.
+      attr_reader :type
+
+      def initialize(name, type)
+        raise ArgumentError, 'Invalid type' unless Api::Enums::V1::IndexedValueType.lookup(type)
+
+        @name = name
+        @type = type
+      end
+
+      # @return [Boolean] Check equality.
+      def ==(other)
+        other.is_a?(Key) && other.name == @name && other.type == @type
+      end
+
+      alias eql? ==
+
+      # @return [Integer] Hash
+      def hash
+        [self.class, @name, @age].hash
+      end
+
+      # Validate that the given value matches the expected {#type}.
+      #
+      # @raise [TypeError] The value does not have the proper type.
+      def validate_value(value)
+        case type
+        when IndexedValueType::TEXT
+          raise TypeError, 'Value of TEXT key must be a String' unless value.is_a?(String)
+        when IndexedValueType::KEYWORD
+          raise TypeError, 'Value of KEYWORD key must be a String' unless value.is_a?(String)
+        when IndexedValueType::INTEGER
+          raise TypeError, 'Value of INTEGER key must be a Integer' unless value.is_a?(Integer)
+        when IndexedValueType::FLOAT
+          unless value.is_a?(Float) || value.is_a?(Integer)
+            raise TypeError, 'Value of FLOAT key must be a Float or Integer'
+          end
+        when IndexedValueType::BOOLEAN
+          unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+            raise TypeError, 'Value of BOOLEAN key must be a Boolean'
+          end
+        when IndexedValueType::TIME
+          raise TypeError, 'Value of TIME key must be a Time' unless value.is_a?(Time)
+        when IndexedValueType::KEYWORD_LIST
+          unless value.is_a?(Array) && value.all? { |v| v.is_a?(String) }
+            raise TypeError, 'Value of KEYWORD_LIST key must be an Array of String'
+          end
+        else
+          # Should never happen, checked in constructor
+          raise 'Unrecognized key type'
+        end
+      end
+
+      # Create an updated that sets the given value for this key.
+      #
+      # @param value [Object] Value to update. Must be the proper type for the key.
+      # @return [Update] Created update.
+      def value_set(value)
+        raise ArgumentError, 'Value cannot be nil, use value_unset' if value.nil?
+
+        Update.new(self, value)
+      end
+
+      # Create an updated that unsets the key.
+      #
+      # @return [Update] Created update.
+      def value_unset
+        Update.new(self, nil)
+      end
+    end
+
+    # Search attribute update that can be separately applied.
+    class Update
+      # @return [Key] Key this update applies to.
+      attr_reader :key
+
+      # @return [Object, nil] Value to update or `nil` to remove the key.
+      attr_reader :value
+
+      # Create an update. Users may find it easier to use {Key#value_set} and {Key#value_unset} instead.
+      #
+      # @param key [Key] Key to update.
+      # @param value [Object, nil] Value to update to or nil to remove the value.
+      def initialize(key, value)
+        raise ArgumentError, 'Key must be a key' unless key.is_a?(Key)
+
+        key.validate_value(value) unless value.nil?
+        @key = key
+        @value = value
+      end
+    end
+
+    # @!visibility private
+    def self.from_proto(proto)
+      return nil unless proto
+      raise ArgumentError, 'Expected proto search attribute' unless proto.is_a?(Api::Common::V1::SearchAttributes)
+
+      SearchAttributes.new(proto.indexed_fields.map do |key_name, payload| # rubocop:disable Style/MapToHash
+        key = Key.new(key_name, IndexedValueType::PROTO_VALUES[payload.metadata['type']])
+        value = value_from_payload(payload)
+        [key, value]
+      end.to_h)
+    end
+
+    # @!visibility private
+    def self.value_from_payload(payload)
+      value = Converters::PayloadConverter.default.from_payload(payload)
+      # Time needs to be converted
+      value = Time.iso8601(value) if payload.metadata['type'] == 'DateTime' && value.is_a?(String)
+      value
+    end
+
+    # Create a search attribute collection.
+    #
+    # @param existing [SearchAttributes, Hash<Key, Object>, nil] Existing collection. This can be another
+    #   {SearchAttributes} instance or a {::Hash}.
+    def initialize(existing = nil)
+      if existing.nil?
+        @raw_hash = {}
+      elsif existing.is_a?(SearchAttributes)
+        @raw_hash = existing.to_h
+      elsif existing.is_a?(Hash)
+        @raw_hash = {}
+        existing.each { |key, value| self[key] = value }
+      else
+        raise ArgumentError, 'Existing must be nil, a SearchAttributes instance, or a valid Hash'
+      end
+    end
+
+    # Set a search attribute value for a key. This will replace any existing value for the {Key#name }regardless of
+    # {Key#type}.
+    #
+    # @param key [Key] A key to set. This must be a {Key} and the value must be proper for the {Key#type}.
+    # @param value [Object, nil] The value to set. If `nil`, the key is removed. The value must be proper for the `key`.
+    def []=(key, value)
+      # Key must be a Key
+      raise ArgumentError, 'Key must be a key' unless key.is_a?(Key)
+
+      key.validate_value(value) unless value.nil?
+
+      # Remove any key with the same name and set
+      delete(key)
+      # We only set the value if it's non-nil, otherwise it's a delete
+      @raw_hash[key] = value unless value.nil?
+    end
+
+    # Get a search attribute value for a key.
+    #
+    # @param key [Key, String] The key to find. If this is a {Key}, it will use key equality (i.e. name and type) to
+    #   search. If this is a {::String}, the type is not checked when finding the proper key.
+    # @return [Object, nil] Value if found or `nil` if not.
+    def [](key)
+      # Key must be a Key or a string
+      if key.is_a?(Key)
+        @raw_hash[key]
+      elsif key.is_a?(String)
+        @raw_hash.find { |hash_key, _| hash_key.name == key }&.last
+      else
+        raise ArgumentError, 'Key must be a key or string'
+      end
+    end
+
+    # Delete a search attribute key
+    #
+    # @param key [Key, String] The key to delete. Regardless of whether this is a {Key} or a {::String}, the key with
+    #   the matching name will be deleted. This means a {Key} with a matching name but different type may be deleted.
+    def delete(key)
+      # Key must be a Key or a string, but we delete all values for the
+      # name no matter what
+      name = if key.is_a?(Key)
+               key.name
+             elsif key.is_a?(String)
+               key
+             else
+               raise ArgumentError, 'Key must be a key or string'
+             end
+      @raw_hash.delete_if { |hash_key, _| hash_key.name == name }
+    end
+
+    # Like {::Hash#each}.
+    def each(&)
+      @raw_hash.each(&)
+    end
+
+    # @return [Hash<Key, Object>] Copy of the search attributes as a hash.
+    def to_h
+      @raw_hash.dup
+    end
+
+    # @return [SearchAttributes] Copy of the search attributes.
+    def dup
+      SearchAttributes.new(self)
+    end
+
+    # @return [Boolean] Whether the set of attributes is empty.
+    def empty?
+      length.zero?
+    end
+
+    # @return [Integer] Number of attributes.
+    def length
+      @raw_hash.length
+    end
+
+    alias size length
+
+    # Return a new search attributes collection with updates applied.
+    #
+    # @param updates [Update] Updates created via {Key#value_set} or {Key#value_unset}.
+    # @return [SearchAttributes] New collection.
+    def update(*updates)
+      attrs = dup
+      attrs.update!(*updates)
+      attrs
+    end
+
+    # Update this search attribute collection with given updates.
+    #
+    # @param updates [Update] Updates created via {Key#value_set} or {Key#value_unset}.
+    def update!(*updates)
+      updates.each do |update|
+        raise ArgumentError, 'Update must be an update' unless update.is_a?(Update)
+
+        self[update.key] = update.value
+      end
+    end
+
+    # @!visibility private
+    def to_proto
+      Api::Common::V1::SearchAttributes.new(
+        indexed_fields: @raw_hash.to_h do |key, value|
+          # We use a default converter, but if type is a time, we need ISO format
+          value = value.iso8601 if key.type == IndexedValueType::TIME
+
+          # Convert to payload
+          payload = Converters::PayloadConverter.default.to_payload(value)
+          payload.metadata['type'] = IndexedValueType::PROTO_NAMES[key.type]
+
+          [key.name, payload]
+        end
+      )
+    end
+
+    # Type for a search attribute key/value.
+    #
+    # @see https://docs.temporal.io/visibility#supported-types
+    module IndexedValueType
+      # Text type, values must be {::String}.
+      TEXT = Api::Enums::V1::IndexedValueType::INDEXED_VALUE_TYPE_TEXT
+
+      # Keyword type, values must be {::String}.
+      KEYWORD = Api::Enums::V1::IndexedValueType::INDEXED_VALUE_TYPE_KEYWORD
+
+      # Integer type, values must be {::Integer}.
+      INTEGER = Api::Enums::V1::IndexedValueType::INDEXED_VALUE_TYPE_INT
+
+      # Float type, values must be {::Float} or {::Integer}.
+      FLOAT = Api::Enums::V1::IndexedValueType::INDEXED_VALUE_TYPE_DOUBLE
+
+      # Boolean type, values must be {::TrueClass} or {::FalseClass}.
+      BOOLEAN = Api::Enums::V1::IndexedValueType::INDEXED_VALUE_TYPE_BOOL
+
+      # Time type, values must be {::Time}.
+      TIME = Api::Enums::V1::IndexedValueType::INDEXED_VALUE_TYPE_DATETIME
+
+      # Keyword list type, values must be {::Array<String>}.
+      KEYWORD_LIST = Api::Enums::V1::IndexedValueType::INDEXED_VALUE_TYPE_KEYWORD_LIST
+
+      # @!visibility private
+      PROTO_NAMES = {
+        TEXT => 'Text',
+        KEYWORD => 'Keyword',
+        INTEGER => 'Int',
+        FLOAT => 'Double',
+        BOOLEAN => 'Bool',
+        TIME => 'DateTime',
+        KEYWORD_LIST => 'KeywordList'
+      }.freeze
+
+      # @!visibility private
+      PROTO_VALUES = PROTO_NAMES.invert.freeze
+    end
+  end
+end