temporalio 0.2.0 → 0.4.0

data/lib/temporalio/runtime.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
+require 'temporalio/internal/bridge'
 require 'temporalio/internal/bridge/runtime'
+require 'temporalio/internal/metric'
+require 'temporalio/metric'
+require 'temporalio/runtime/metric_buffer'
 
 module Temporalio
   # Runtime for Temporal Ruby SDK.
@@ -9,6 +13,11 @@ module Temporalio
   # 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
+    TelemetryOptions = Data.define(
+      :logging,
+      :metrics
+    )
+
     # Telemetry options for the runtime.
     #
     # @!attribute logging
@@ -16,15 +25,13 @@ module Temporalio
     #     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)
+    class TelemetryOptions
+      # Create telemetry options.
+      #
+      # @param logging [LoggingOptions, nil] Logging options, default is new {LoggingOptions} with no parameters. Can be
+      #   set to nil to disable logging.
+      # @param metrics [MetricsOptions, nil] Metrics options.
+      def initialize(logging: LoggingOptions.new, metrics: nil)
         super
       end
 
@@ -38,20 +45,21 @@ module Temporalio
       end
     end
 
+    LoggingOptions = Data.define(
+      :log_filter
+      # TODO(cretz): forward_to
+    )
+
     # 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)
+    class LoggingOptions
+      # Create logging options
+      #
+      # @param log_filter [LoggingFilterOptions, String] Logging filter for Core.
+      def initialize(log_filter: LoggingFilterOptions.new)
         super
       end
 
@@ -70,22 +78,23 @@ module Temporalio
       end
     end
 
+    LoggingFilterOptions = Data.define(
+      :core_level,
+      :other_level
+    )
+
     # Logging filter options for Core.
     #
     # @!attribute core_level
-    #   @return ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'] Log level for Core log messages, default is +'WARN'+.
+    #   @return ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'] Log level for Core log messages.
     # @!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)
+    #   @return ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'] Log level for other Rust log messages.
+    class LoggingFilterOptions
+      # Create logging filter options.
+      #
+      # @param core_level ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'] Log level for Core log messages.
+      # @!attribute other_level ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'] Log level for other Rust log messages.
+      def initialize(core_level: 'WARN', other_level: 'ERROR')
         super
       end
 
@@ -96,32 +105,56 @@ module Temporalio
       end
     end
 
+    MetricsOptions = Data.define(
+      :opentelemetry,
+      :prometheus,
+      :buffer,
+      :attach_service_name,
+      :global_tags,
+      :metric_prefix
+    )
+
     # 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+.
+    #     exclusive with `prometheus` and `buffer`.
     # @!attribute prometheus
     #   @return [PrometheusMetricsOptions, nil] Prometheus options if using Prometheus. This is mutually exclusive with
-    #     +opentelemetry+.
+    #     `opentelemetry` and `buffer`.
+    # @!attribute buffer
+    #   @return [MetricBuffer, nil] Metric buffer to send all metrics to. This is mutually exclusive with `prometheus`
+    #     and `opentelemetry`.
     # @!attribute attach_service_name
-    #   @return [Boolean] Whether to put the service_name on every metric, default +true+.
+    #   @return [Boolean] Whether to put the service_name on every metric.
     # @!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)
+    #   @return [String, nil] Prefix to put on every Temporal metric. If unset, defaults to `temporal_`.
+    class MetricsOptions
+      # Create metrics options. Either `opentelemetry` or `prometheus` required, but not both.
+      #
+      # @param opentelemetry [OpenTelemetryMetricsOptions, nil] OpenTelemetry options if using OpenTelemetry. This is
+      #   mutually exclusive with `prometheus` and `buffer`.
+      # @param prometheus [PrometheusMetricsOptions, nil] Prometheus options if using Prometheus. This is mutually
+      #   exclusive with `opentelemetry` and `buffer`.
+      # @param buffer [MetricBuffer, nil] Metric buffer to send all metrics to. This is mutually exclusive with
+      #   `prometheus` and `opentelemetry`.
+      # @param attach_service_name [Boolean] Whether to put the service_name on every metric.
+      # @param global_tags [Hash<String, String>, nil] Resource tags to be applied to all metrics.
+      # @param metric_prefix [String, nil] Prefix to put on every Temporal metric. If unset, defaults to `temporal_`.
+      def initialize(
+        opentelemetry: nil,
+        prometheus: nil,
+        buffer: nil,
+        attach_service_name: true,
+        global_tags: nil,
+        metric_prefix: nil
+      )
+        if [opentelemetry, prometheus, buffer].count { |v| !v.nil? } > 1
+          raise 'Can only have one of opentelemetry, prometheus, or buffer'
+        end
+
         super
       end
 
@@ -131,6 +164,7 @@ module Temporalio
         Internal::Bridge::Runtime::MetricsOptions.new(
           opentelemetry: opentelemetry&._to_bridge,
           prometheus: prometheus&._to_bridge,
+          buffered_with_size: buffer&._buffer_size,
           attach_service_name:,
           global_tags:,
           metric_prefix:
@@ -138,6 +172,16 @@ module Temporalio
       end
     end
 
+    OpenTelemetryMetricsOptions = Data.define(
+      :url,
+      :headers,
+      :metric_periodicity,
+      :metric_temporality,
+      :durations_as_seconds,
+      :http,
+      :histogram_bucket_overrides
+    )
+
     # Options for exporting metrics to OpenTelemetry.
     #
     # @!attribute url
@@ -152,25 +196,38 @@ module Temporalio
     # @!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
+    # @!attribute http
+    #   @return [Boolean] True if the protocol is HTTP, false if gRPC (the default).
+    # @!attribute histogram_bucket_overrides
+    #   @return [Hash<String, Array<Numeric>>, nil] Override default histogram buckets. Key of the hash it the metric
+    #     name, value is an array of floats for the set of buckets.
+    class OpenTelemetryMetricsOptions
       # OpenTelemetry metric temporality.
-      module MetricTemporality # rubocop:disable Lint/ConstantDefinitionInBlock
+      module MetricTemporality
         CUMULATIVE = 1
         DELTA = 2
       end
 
-      # @!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)
+      # Create OpenTelemetry options.
+      #
+      # @param url [String] URL for OpenTelemetry endpoint.
+      # @param headers [Hash<String, String>, nil] Headers for OpenTelemetry endpoint.
+      # @param metric_periodicity [Float, nil] How frequently metrics should be exported, unset uses internal default.
+      # @param metric_temporality [MetricTemporality] How frequently metrics should be exported.
+      # @param durations_as_seconds [Boolean] Whether to use float seconds instead of integer milliseconds for
+      #   durations.
+      # @param http [Boolean] True if the protocol is HTTP, false if gRPC (the default).
+      # @param histogram_bucket_overrides [Hash<String, Array<Numeric>>, nil] Override default histogram buckets. Key of
+      #   the hash it the metric name, value is an array of floats for the set of buckets.
+      def initialize(
+        url:,
+        headers: nil,
+        metric_periodicity: nil,
+        metric_temporality: MetricTemporality::CUMULATIVE,
+        durations_as_seconds: false,
+        http: false,
+        histogram_bucket_overrides: nil
+      )
         super
       end
 
@@ -186,35 +243,51 @@ module Temporalio
                                     when MetricTemporality::DELTA then true
                                     else raise 'Unrecognized metric temporality'
                                     end,
-          durations_as_seconds:
+          durations_as_seconds:,
+          http:,
+          histogram_bucket_overrides:
         )
       end
     end
 
+    PrometheusMetricsOptions = Data.define(
+      :bind_address,
+      :counters_total_suffix,
+      :unit_suffix,
+      :durations_as_seconds,
+      :histogram_bucket_overrides
+    )
+
     # 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+.
+    #   @return [Boolean] If `true`, all counters will include a `_total` suffix.
     # @!attribute unit_suffix
-    #   @return [Boolean] If +true+, all histograms will include the unit in their name as a suffix, default is +false+.
+    #   @return [Boolean] If `true`, all histograms will include the unit in their name as a suffix.
     # @!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)
+    #   @return [Boolean] Whether to use float seconds instead of integer milliseconds for durations.
+    # @!attribute histogram_bucket_overrides
+    #   @return [Hash<String, Array<Numeric>>, nil] Override default histogram buckets. Key of the hash it the metric
+    #     name, value is an array of floats for the set of buckets.
+    class PrometheusMetricsOptions
+      # Create Prometheus options.
+      #
+      # @param bind_address [String] Address to bind to for Prometheus endpoint.
+      # @param counters_total_suffix [Boolean] If `true`, all counters will include a `_total` suffix.
+      # @param unit_suffix [Boolean] If `true`, all histograms will include the unit in their name as a suffix.
+      # @param durations_as_seconds [Boolean] Whether to use float seconds instead of integer milliseconds for
+      #   durations.
+      # @param histogram_bucket_overrides [Hash<String, Array<Numeric>>, nil] Override default histogram buckets. Key of
+      #   the hash it the metric name, value is an array of floats for the set of buckets.
+      def initialize(
+        bind_address:,
+        counters_total_suffix: false,
+        unit_suffix: false,
+        durations_as_seconds: false,
+        histogram_bucket_overrides: nil
+      )
         super
       end
 
@@ -225,7 +298,8 @@ module Temporalio
           bind_address:,
           counters_total_suffix:,
           unit_suffix:,
-          durations_as_seconds:
+          durations_as_seconds:,
+          histogram_bucket_overrides:
         )
       end
     end
@@ -248,14 +322,21 @@ module Temporalio
       @default = runtime
     end
 
+    # @return [Metric::Meter] Metric meter that can create and record metric values.
+    attr_reader :metric_meter
+
     # 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)
+      # Set runtime on the buffer which will fail if the buffer is used on another runtime
+      telemetry.metrics&.buffer&._set_runtime(self)
+
       @core_runtime = Internal::Bridge::Runtime.new(
         Internal::Bridge::Runtime::Options.new(telemetry: telemetry._to_bridge)
       )
+      @metric_meter = Internal::Metric::Meter.create_from_runtime(self) || Metric::Meter.null
       # 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

data/lib/temporalio/search_attributes.rb

@@ -7,7 +7,7 @@ module Temporalio
   #
   # 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 is immutable for outside use.
   class SearchAttributes
     # Key for a search attribute.
     class Key
@@ -20,7 +20,7 @@ module Temporalio
       def initialize(name, type)
         raise ArgumentError, 'Invalid type' unless Api::Enums::V1::IndexedValueType.lookup(type)
 
-        @name = name
+        @name = name.to_s
         @type = type
       end
 
@@ -104,28 +104,54 @@ module Temporalio
         @key = key
         @value = value
       end
+
+      # @!visibility private
+      def _to_proto_pair
+        SearchAttributes._to_proto_pair(key, 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)
+    def self._from_proto(proto, disable_mutations: false, never_nil: false)
+      return nil unless proto || never_nil
+
+      attrs = if proto
+                unless proto.is_a?(Api::Common::V1::SearchAttributes)
+                  raise ArgumentError, 'Expected proto search attribute'
+                end
+
+                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)
+              else
+                SearchAttributes.new
+              end
+      attrs._disable_mutations = disable_mutations
+      attrs
     end
 
     # @!visibility private
-    def self.value_from_payload(payload)
+    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
 
+    # @!visibility private
+    def self._to_proto_pair(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 && value.is_a?(Time)
+
+      # Convert to payload
+      payload = Converters::PayloadConverter.default.to_payload(value)
+      payload.metadata['type'] = IndexedValueType::PROTO_NAMES[key.type]
+
+      [key.name, payload]
+    end
+
     # Create a search attribute collection.
     #
     # @param existing [SearchAttributes, Hash<Key, Object>, nil] Existing collection. This can be another
@@ -149,6 +175,7 @@ module Temporalio
     # @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)
+      _assert_mutations_enabled
       # Key must be a Key
       raise ArgumentError, 'Key must be a key' unless key.is_a?(Key)
 
@@ -162,33 +189,37 @@ module Temporalio
 
     # 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.
+    # @param key [Key, String, Symbol] 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)
+      case key
+      when Key
         @raw_hash[key]
-      elsif key.is_a?(String)
-        @raw_hash.find { |hash_key, _| hash_key.name == key }&.last
+      when String, Symbol
+        @raw_hash.find { |hash_key, _| hash_key.name == key.to_s }&.last
       else
-        raise ArgumentError, 'Key must be a key or string'
+        raise ArgumentError, 'Key must be a key or string/symbol'
       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.
+    # @param key [Key, String, Symbol] 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)
+      _assert_mutations_enabled
       # 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)
+      name = case key
+             when Key
                key.name
-             elsif key.is_a?(String)
-               key
+             when String, Symbol
+               key.to_s
              else
-               raise ArgumentError, 'Key must be a key or string'
+               raise ArgumentError, 'Key must be a key or string/symbol'
              end
       @raw_hash.delete_if { |hash_key, _| hash_key.name == name }
     end
@@ -205,7 +236,9 @@ module Temporalio
 
     # @return [SearchAttributes] Copy of the search attributes.
     def dup
-      SearchAttributes.new(self)
+      attrs = SearchAttributes.new(self)
+      attrs._disable_mutations = false
+      attrs
     end
 
     # @return [Boolean] Whether the set of attributes is empty.
@@ -218,6 +251,14 @@ module Temporalio
       @raw_hash.length
     end
 
+    # Check equality.
+    #
+    # @param other [SearchAttributes] To compare.
+    # @return [Boolean] Whether equal.
+    def ==(other)
+      other.is_a?(SearchAttributes) && @raw_hash == other._raw_hash
+    end
+
     alias size length
 
     # Return a new search attributes collection with updates applied.
@@ -225,6 +266,7 @@ module Temporalio
     # @param updates [Update] Updates created via {Key#value_set} or {Key#value_unset}.
     # @return [SearchAttributes] New collection.
     def update(*updates)
+      _assert_mutations_enabled
       attrs = dup
       attrs.update!(*updates)
       attrs
@@ -234,27 +276,41 @@ module Temporalio
     #
     # @param updates [Update] Updates created via {Key#value_set} or {Key#value_unset}.
     def update!(*updates)
+      _assert_mutations_enabled
       updates.each do |update|
         raise ArgumentError, 'Update must be an update' unless update.is_a?(Update)
 
-        self[update.key] = update.value
+        if update.value.nil?
+          delete(update.key)
+        else
+          self[update.key] = update.value
+        end
       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
+    def _raw_hash
+      @raw_hash
+    end
 
-          # Convert to payload
-          payload = Converters::PayloadConverter.default.to_payload(value)
-          payload.metadata['type'] = IndexedValueType::PROTO_NAMES[key.type]
+    # @!visibility private
+    def _to_proto
+      Api::Common::V1::SearchAttributes.new(indexed_fields: _to_proto_hash)
+    end
 
-          [key.name, payload]
-        end
-      )
+    # @!visibility private
+    def _to_proto_hash
+      @raw_hash.to_h { |key, value| SearchAttributes._to_proto_pair(key, value) }
+    end
+
+    # @!visibility private
+    def _assert_mutations_enabled
+      raise 'Search attribute mutations disabled' if @disable_mutations
+    end
+
+    # @!visibility private
+    def _disable_mutations=(value)
+      @disable_mutations = value
     end
 
     # Type for a search attribute key/value.