txlemetry-ruby 4.0.0

data/lib/txlemetry/defaults.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module Defaults
+    MAX_HASH_SIZE = 50_000
+
+    module Request
+      HOST = 'app.txlemetry.com'
+      PORT = 443
+      PATH = '/batch/'
+      SSL = true
+      HEADERS = {
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+        'User-Agent' => "txlemetry-ruby/#{Txlemetry::VERSION}"
+      }.freeze
+      RETRIES = 10
+    end
+
+    module FeatureFlags
+      FLAG_REQUEST_TIMEOUT_SECONDS = 3
+      POLLING_INTERVAL_SECONDS = 30
+      # Number of retries for a flag request after a transient network error.
+      # Flag requests are stateless and cause no server-side mutation, so
+      # retrying is safe.
+      FLAG_REQUEST_MAX_RETRIES = 1
+    end
+
+    module Queue
+      MAX_SIZE = 10_000
+    end
+
+    module Message
+      MAX_BYTES = 32_768 # 32Kb
+    end
+
+    module MessageBatch
+      MAX_BYTES = 512_000 # 500Kb
+      MAX_SIZE = 100
+      FLUSH_INTERVAL_SECONDS = 5.0 # seconds
+    end
+
+    module BackoffPolicy
+      MIN_TIMEOUT_MS = 100
+      MAX_TIMEOUT_MS = 10_000
+      MULTIPLIER = 1.5
+      RANDOMIZATION_FACTOR = 0.5
+    end
+  end
+end

data/lib/txlemetry/exception_capture.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+# Portions of this file are derived from getsentry/sentry-ruby
+# Copyright (c) 2020 Sentry
+# Licensed under the MIT License: https://github.com/getsentry/sentry-ruby/blob/master/LICENSE
+# - sentry-ruby/lib/sentry/interfaces/single_exception.rb
+# - sentry-ruby/lib/sentry/interfaces/stacktrace_builder.rb
+# - sentry-ruby/lib/sentry/backtrace.rb
+# - sentry-ruby/lib/sentry/interfaces/stacktrace.rb
+# - sentry-ruby/lib/sentry/linecache.rb
+
+# 💖 open source (under MIT License)
+
+module Txlemetry
+  # Builds Txlemetry exception payloads from Ruby exception objects.
+  #
+  # @api private
+  module ExceptionCapture
+    RUBY_INPUT_FORMAT = /
+        ^ \s* (?: [a-zA-Z]: | uri:classloader: )? ([^:]+ | <.*>):
+        (\d+)
+        (?: :in\s('|`)(?:([\w:]+)\#)?([^']+)')?$
+      /x
+
+    # Maximum number of exceptions extracted from a single `cause` chain.
+    MAX_CHAINED_EXCEPTIONS = 50
+
+    DEFAULT_MECHANISM = { 'type' => 'generic', 'handled' => true }.freeze
+
+    # Builds the `$exception_list` payload for an exception, walking its
+    # `cause` chain outermost-first (wrapper first, root cause last).
+    #
+    # @param value [Exception, String, Object] Exception input to parse.
+    # @param mechanism [Hash, nil] Mechanism applied to the outermost exception,
+    #   e.g. `{ 'type' => 'rails', 'handled' => false }`. Chained causes are
+    #   tagged with `{ 'type' => 'chained', ... }` and parent linkage.
+    # @return [Array<Hash>, nil] Parsed exception payloads, or nil when the input is unsupported.
+    def self.build_exception_list(value, mechanism: nil)
+      root_mechanism = DEFAULT_MECHANISM.merge(mechanism || {})
+
+      exceptions = []
+      seen = {}.compare_by_identity
+      current = value
+
+      while current && exceptions.length < MAX_CHAINED_EXCEPTIONS && !seen.key?(current)
+        parsed = build_parsed_exception(current, mechanism: chain_mechanism(root_mechanism, exceptions.length))
+        break if parsed.nil?
+
+        exceptions << parsed
+        seen[current] = true
+        current = current.respond_to?(:cause) ? current.cause : nil
+      end
+
+      exceptions.empty? ? nil : exceptions
+    end
+
+    # @param root_mechanism [Hash] Mechanism of the outermost exception.
+    # @param exception_id [Integer] Zero-based position in the cause chain.
+    # @return [Hash]
+    def self.chain_mechanism(root_mechanism, exception_id)
+      mechanism = root_mechanism.merge('exception_id' => exception_id)
+      return mechanism if exception_id.zero?
+
+      mechanism.merge(
+        'type' => 'chained',
+        'source' => 'cause',
+        'parent_id' => exception_id - 1
+      )
+    end
+
+    # @param value [Exception, String, Object] Exception input to parse.
+    # @param mechanism [Hash, nil] Mechanism describing how the exception was captured.
+    # @return [Hash, nil] Parsed exception payload, or nil when the input is unsupported.
+    def self.build_parsed_exception(value, mechanism: nil)
+      title, message, backtrace = coerce_exception_input(value)
+      return nil if title.nil?
+
+      build_single_exception_from_data(title, message, backtrace, mechanism: mechanism)
+    end
+
+    # @param title [String]
+    # @param message [String, nil]
+    # @param backtrace [Array<String>, nil]
+    # @param mechanism [Hash, nil]
+    # @return [Hash]
+    def self.build_single_exception_from_data(title, message, backtrace, mechanism: nil)
+      {
+        'type' => title,
+        'value' => message || '',
+        'mechanism' => DEFAULT_MECHANISM.merge(mechanism || {}),
+        'stacktrace' => build_stacktrace(backtrace)
+      }
+    end
+
+    # @param backtrace [Array<String>, nil]
+    # @return [Hash, nil]
+    def self.build_stacktrace(backtrace)
+      return nil unless backtrace && !backtrace.empty?
+
+      root = project_root
+      roots = dependency_roots(root)
+      frames = backtrace.first(50).map do |line|
+        parse_backtrace_line(line, project_root: root, dependency_roots: roots)
+      end.compact.reverse
+
+      {
+        'type' => 'raw',
+        'frames' => frames
+      }
+    end
+
+    # @param line [String]
+    # @param project_root [String, nil] Project root used to derive project-relative filenames.
+    # @param dependency_roots [Array<String>, nil] Cached gem and stdlib roots.
+    # @return [Hash, nil]
+    def self.parse_backtrace_line(line, project_root: self.project_root, dependency_roots: nil)
+      match = line.match(RUBY_INPUT_FORMAT)
+      return nil unless match
+
+      file = match[1]
+      lineno = match[2].to_i
+      method_name = match[5]
+
+      frame = {
+        'filename' => frame_filename(file, project_root),
+        'abs_path' => file,
+        'lineno' => lineno,
+        'function' => method_name,
+        'in_app' => !gem_path?(file, dependency_roots || self.dependency_roots(project_root)),
+        'platform' => 'ruby'
+      }
+
+      add_context_lines(frame, file, lineno) if frame['in_app'] && File.exist?(file)
+
+      frame
+    end
+
+    # Root directory the application runs from, used to derive stable
+    # project-relative filenames from per-host deploy paths
+    # (e.g. `/app/releases/20240101/...`).
+    #
+    # @return [String]
+    def self.project_root
+      if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+        ::Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    rescue StandardError
+      Dir.pwd
+    end
+
+    # Stable filename used for fingerprinting: the project-relative path when
+    # the file lives inside the project root, its basename otherwise. The raw
+    # absolute path is kept separately in `abs_path`.
+    #
+    # @param path [String]
+    # @param project_root [String, nil]
+    # @return [String]
+    def self.frame_filename(path, project_root)
+      if project_root && !project_root.empty? && path_within?(path, project_root)
+        relative = path[project_root.length..]
+        relative = relative[1..] while relative.start_with?(File::SEPARATOR)
+        return relative unless relative.empty?
+      end
+
+      File.basename(path)
+    end
+
+    # Whether the path belongs to an installed gem or the Ruby standard library,
+    # based on gem install locations rather than path substrings.
+    #
+    # @param path [String]
+    # @param dependency_roots [Array<String>]
+    # @return [Boolean]
+    def self.gem_path?(path, dependency_roots = self.dependency_roots)
+      dependency_roots.any? { |root| path_within?(path, root) }
+    end
+
+    # @param project_root [String]
+    # @return [Array<String>] Directories containing installed gems and the Ruby stdlib.
+    def self.dependency_roots(project_root = self.project_root)
+      roots = []
+      if defined?(Gem)
+        roots.concat(Gem.path) if Gem.respond_to?(:path)
+        roots << Gem.default_dir if Gem.respond_to?(:default_dir)
+        roots.concat(Gem.loaded_specs.each_value.map(&:full_gem_path)) if Gem.respond_to?(:loaded_specs)
+      end
+      roots << RbConfig::CONFIG['rubylibprefix'] if defined?(RbConfig)
+      # The project itself can be a loaded spec (e.g. a gem developed in place,
+      # or a Rails engine); its frames are still application code.
+      roots.compact.reject(&:empty?).uniq - [project_root]
+    rescue StandardError
+      []
+    end
+
+    # @param path [String]
+    # @param root [String]
+    # @return [Boolean]
+    def self.path_within?(path, root)
+      root = root.chomp(File::SEPARATOR)
+      path == root || path.start_with?("#{root}#{File::SEPARATOR}")
+    end
+
+    # @param frame [Hash]
+    # @param file_path [String]
+    # @param lineno [Integer]
+    # @param context_size [Integer]
+    # @return [void]
+    def self.add_context_lines(frame, file_path, lineno, context_size = 5)
+      lines = File.readlines(file_path)
+      return if lines.empty?
+
+      return unless lineno.positive? && lineno <= lines.length
+
+      pre_context_start = [lineno - context_size, 1].max
+      post_context_end = [lineno + context_size, lines.length].min
+
+      frame['context_line'] = lines[lineno - 1].chomp
+
+      frame['pre_context'] = lines[(pre_context_start - 1)...(lineno - 1)].map(&:chomp) if pre_context_start < lineno
+
+      frame['post_context'] = lines[lineno...(post_context_end)].map(&:chomp) if post_context_end > lineno
+    rescue StandardError
+      # Silently ignore file read errors
+    end
+
+    # @param value [Exception, String, Object]
+    # @return [Array] Three-item array of title, message, and backtrace.
+    def self.coerce_exception_input(value)
+      if value.is_a?(String)
+        title = 'Error'
+        message = value
+        backtrace = nil
+      elsif value.respond_to?(:backtrace) && value.respond_to?(:message)
+        title = value.class.to_s
+        message = value.message || ''
+        backtrace = value.backtrace
+      else
+        return [nil, nil, nil]
+      end
+
+      [title, message, backtrace]
+    end
+  end
+end

data/lib/txlemetry/feature_flag.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  # Represents a feature flag returned by /flags v2.
+  #
+  # @api private
+  class FeatureFlag
+    attr_reader :key, :enabled, :variant, :reason, :metadata, :failed
+
+    # @param json [Hash] Raw feature flag data returned by /flags.
+    def initialize(json)
+      json.transform_keys!(&:to_s)
+      @key = json['key']
+      @enabled = json['enabled']
+      @variant = json['variant']
+      @reason = json['reason'] ? EvaluationReason.new(json['reason']) : nil
+      @metadata = json['metadata'] ? FeatureFlagMetadata.new(json['metadata'].transform_keys(&:to_s)) : nil
+      @failed = json['failed']
+    end
+
+    # @return [String, Boolean] The variant value when present, otherwise the enabled status.
+    # TODO: Rename to `value` in future version
+    def get_value # rubocop:disable Naming/AccessorMethodName
+      @variant || @enabled
+    end
+
+    # @return [Object, nil] The flag payload from metadata.
+    def payload
+      @metadata&.payload
+    end
+
+    # @param key [String, Symbol] The feature flag key.
+    # @param value [String, Boolean] The feature flag value.
+    # @param payload [Object, nil] The feature flag payload.
+    # @return [Txlemetry::FeatureFlag]
+    def self.from_value_and_payload(key, value, payload)
+      new({
+            'key' => key,
+            'enabled' => value.is_a?(String) || value,
+            'variant' => value.is_a?(String) ? value : nil,
+            'reason' => nil,
+            'metadata' => {
+              'id' => nil,
+              'version' => nil,
+              'payload' => payload,
+              'description' => nil
+            }
+          })
+    end
+  end
+
+  # Represents the reason why a flag was enabled/disabled.
+  #
+  # @api private
+  class EvaluationReason
+    attr_reader :code, :description, :condition_index
+
+    # @param json [Hash] Raw reason data returned by /flags.
+    def initialize(json)
+      json.transform_keys!(&:to_s)
+      @code = json['code']
+      @description = json['description']
+      @condition_index = json['condition_index'].to_i if json['condition_index']
+    end
+  end
+
+  # Represents metadata about a feature flag.
+  #
+  # @api private
+  class FeatureFlagMetadata
+    attr_reader :id, :version, :payload, :description, :has_experiment
+
+    # @param json [Hash] Raw metadata returned by /flags.
+    def initialize(json)
+      json.transform_keys!(&:to_s)
+      @id = json['id']
+      @version = json['version']
+      @payload = json['payload']
+      @description = json['description']
+      # Whether the flag is linked to an experiment. nil when the server
+      # (an older deployment) does not report the field.
+      @has_experiment = json['has_experiment']
+    end
+  end
+end

data/lib/txlemetry/feature_flag_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  # Error type constants for the $feature_flag_error property.
+  #
+  # These values are sent in analytics events to track flag evaluation failures.
+  # They should not be changed without considering impact on existing dashboards
+  # and queries that filter on these values.
+  #
+  # Error values:
+  #   ERRORS_WHILE_COMPUTING: Server returned errorsWhileComputingFlags=true
+  #   FLAG_MISSING: Requested flag not in API response
+  #   QUOTA_LIMITED: Rate/quota limit exceeded
+  #   TIMEOUT: Request timed out
+  #   CONNECTION_ERROR: Network connectivity issue
+  #   UNKNOWN_ERROR: Unexpected exceptions
+  #
+  # For API errors with status codes, use the api_error() method which returns
+  # a string like "api_error_500".
+  # @api private
+  class FeatureFlagError
+    ERRORS_WHILE_COMPUTING = 'errors_while_computing_flags'
+    FLAG_MISSING = 'flag_missing'
+    QUOTA_LIMITED = 'quota_limited'
+    TIMEOUT = 'timeout'
+    CONNECTION_ERROR = 'connection_error'
+    UNKNOWN_ERROR = 'unknown_error'
+
+    # Generate API error string with status code.
+    #
+    # @param status [Integer, String] The HTTP status code
+    # @return [String] Error string in format "api_error_STATUS"
+    def self.api_error(status)
+      "api_error_#{status.to_s.downcase}"
+    end
+  end
+end

data/lib/txlemetry/feature_flag_evaluations.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Txlemetry
+  # A snapshot of feature flag evaluations for one distinct_id, returned by
+  # Txlemetry::Client#evaluate_flags. Calls to {#enabled?} / {#get_flag} fire the
+  # `$feature_flag_called` event (deduped through the existing per-distinct_id
+  # cache); {#get_flag_payload} does not. Pass the snapshot to `capture(flags:)`
+  # to attach `$feature/<key>` and `$active_feature_flags` without a second
+  # /flags request.
+  class FeatureFlagEvaluations
+    EVALUATED_LOCALLY_REASON = 'Evaluated locally'
+
+    EvaluatedFlagRecord = Struct.new(
+      :key, :enabled, :variant, :payload, :id, :version, :reason, :locally_evaluated, :has_experiment,
+      keyword_init: true
+    )
+
+    Host = Struct.new(:capture_flag_called_event_if_needed, :log_warning, keyword_init: true)
+
+    # @return [String] The distinct id these evaluations belong to.
+    attr_reader :distinct_id
+
+    # @return [Hash, nil] Group analytics mapping used for evaluation.
+    attr_reader :groups
+
+    # @return [String, nil] Request id returned by the /flags endpoint.
+    attr_reader :request_id
+
+    # @return [String, nil] Evaluation timestamp returned by the /flags endpoint.
+    attr_reader :evaluated_at
+
+    # @return [Time, nil] When local flag definitions were loaded.
+    attr_reader :flag_definitions_loaded_at
+
+    # @param host [Host, nil] Internal host callbacks used to record flag access events.
+    # @param distinct_id [String, nil] The distinct id these evaluations belong to.
+    # @param flags [Hash] Evaluated flags keyed by flag key.
+    # @param groups [Hash, nil] Group analytics mapping from group type to group key.
+    # @param disable_geoip [Boolean, nil] Whether GeoIP was disabled during evaluation.
+    # @param request_id [String, nil] The request id returned by the /flags endpoint.
+    # @param evaluated_at [String, nil] The evaluation timestamp returned by the /flags endpoint.
+    # @param flag_definitions_loaded_at [Time, nil] When local flag definitions were loaded.
+    # @param errors_while_computing [Boolean] Whether the server reported errors while computing flags.
+    # @param quota_limited [Boolean] Whether feature flag evaluation was quota limited.
+    # @param minimal_flag_called_events [Boolean] Server-controlled gate for minimal
+    #   `$feature_flag_called` events.
+    # @param accessed [Array<String>, Set<String>, nil] Flag keys already accessed by this snapshot.
+    def initialize(
+      host: nil,
+      distinct_id: nil,
+      flags: {},
+      groups: nil,
+      disable_geoip: nil,
+      request_id: nil,
+      evaluated_at: nil,
+      flag_definitions_loaded_at: nil,
+      errors_while_computing: false,
+      quota_limited: false,
+      minimal_flag_called_events: false,
+      accessed: nil
+    )
+      @host = host
+      @distinct_id = distinct_id || ''
+      @flags = flags || {}
+      @groups = groups
+      @disable_geoip = disable_geoip
+      @request_id = request_id
+      @evaluated_at = evaluated_at
+      @flag_definitions_loaded_at = flag_definitions_loaded_at
+      @errors_while_computing = errors_while_computing
+      @quota_limited = quota_limited
+      @minimal_flag_called_events = minimal_flag_called_events == true
+      @accessed = Set.new(accessed || [])
+    end
+
+    # @return [Array<String>] The evaluated flag keys in this snapshot.
+    def keys
+      @flags.keys
+    end
+
+    # @param key [String, Symbol] The feature flag key.
+    # @param default_value [Boolean, nil] Returned when the flag has no value in this
+    #   snapshot — it was never loaded, the `/flags` request failed, or no flag with that
+    #   key exists. A flag that does have a value, including `false` and variant strings,
+    #   always wins over this default; so does a flag the server returned but marked as
+    #   failed, which resolves to `false`. Defaults to `nil`, which keeps the historical
+    #   `false` result for a missing flag.
+    # @return [Boolean] true when the flag is enabled, false when disabled, and the
+    #   caller-supplied default (or false when none was supplied) when the flag is missing.
+    def enabled?(key, default_value: nil)
+      key = key.to_s
+      flag = @flags[key]
+      _record_access(key, flag)
+      return !!default_value if flag.nil? && !default_value.nil?
+
+      flag&.enabled ? true : false
+    end
+
+    # @param key [String, Symbol] The feature flag key.
+    # @return [String, Boolean, nil] Variant string for multivariate flags, true/false for boolean flags,
+    #   or nil when the flag was not returned by the evaluation.
+    def get_flag(key)
+      key = key.to_s
+      flag = @flags[key]
+      _record_access(key, flag)
+      _flag_value(flag)
+    end
+
+    # @param key [String, Symbol] The feature flag key.
+    # @return [Object, nil] The parsed payload for the flag, if any.
+    def get_flag_payload(key)
+      flag = @flags[key.to_s]
+      flag&.payload
+    end
+
+    # Order-dependent: if nothing has been accessed yet, the returned snapshot is
+    # empty. The method honors its name — pre-access flags before calling this if
+    # you want a populated result.
+    # @return [Txlemetry::FeatureFlagEvaluations] A snapshot containing only flags already accessed with
+    #   {#enabled?} or {#get_flag}.
+    def only_accessed
+      _clone_with(@flags.slice(*@accessed))
+    end
+
+    # @param keys [Array<String, Symbol>, String, Symbol] Flag keys to keep in the returned snapshot.
+    # @return [Txlemetry::FeatureFlagEvaluations] A snapshot containing only the requested keys that exist.
+    def only(keys)
+      keys = Array(keys).map(&:to_s)
+      missing = keys.reject { |k| @flags.key?(k) }
+      unless missing.empty?
+        @host.log_warning.call(
+          'FeatureFlagEvaluations#only was called with flag keys that are not in the ' \
+          "evaluation set and will be dropped: #{missing.join(', ')}"
+        )
+      end
+      filtered = @flags.slice(*keys)
+      _clone_with(filtered)
+    end
+
+    # Builds the `$feature/<key>` and `$active_feature_flags` properties for a
+    # captured event. Called from Txlemetry::Client#capture when `flags:` is set.
+    #
+    # @api private
+    # @return [Hash]
+    def _get_event_properties
+      properties = {}
+      active = []
+      @flags.each do |key, flag|
+        properties["$feature/#{key}"] = flag.enabled ? (flag.variant || true) : false
+        active << key if flag.enabled
+      end
+      properties['$active_feature_flags'] = active.sort unless active.empty?
+      properties
+    end
+
+    private
+
+    # Canonical "stored" value for a flag — used for both the
+    # `$feature_flag_response` event property and the dedup cache key, so
+    # `enabled?` and `get_flag` collapse to a single exposure per flag.
+    # Variant string when present, else boolean enabled status; `nil` for
+    # unknown flags.
+    def _flag_value(flag)
+      return nil if flag.nil?
+      return flag.variant if flag.variant
+
+      flag.enabled ? true : false
+    end
+
+    def _record_access(key, flag)
+      @accessed.add(key)
+      return if @distinct_id.nil? || @distinct_id.to_s.empty?
+
+      response = _flag_value(flag)
+      properties = {
+        '$feature_flag' => key,
+        '$feature_flag_response' => response,
+        'locally_evaluated' => flag&.locally_evaluated ? true : false,
+        "$feature/#{key}" => response
+      }
+
+      if flag
+        properties['$feature_flag_has_experiment'] = flag.has_experiment unless flag.has_experiment.nil?
+        properties['$feature_flag_payload'] = flag.payload unless flag.payload.nil?
+        properties['$feature_flag_id'] = flag.id if flag.id
+        properties['$feature_flag_version'] = flag.version if flag.version
+        properties['$feature_flag_reason'] = flag.reason if flag.reason
+        if flag.locally_evaluated && @flag_definitions_loaded_at
+          properties['$feature_flag_definitions_loaded_at'] = @flag_definitions_loaded_at
+        end
+      end
+
+      properties['$feature_flag_request_id'] = @request_id if @request_id
+      properties['$feature_flag_evaluated_at'] = @evaluated_at if @evaluated_at && !(flag && flag.locally_evaluated)
+
+      errors = []
+      errors << 'errors_while_computing_flags' if @errors_while_computing
+      errors << 'quota_limited' if @quota_limited
+      errors << 'flag_missing' if flag.nil?
+      properties['$feature_flag_error'] = errors.join(',') unless errors.empty?
+
+      # Emit a minimal event only when the server gate is on and the flag is
+      # known to have no linked experiment. Any missing signal (unknown flag,
+      # has_experiment absent) fails safe to the full event.
+      minimal = @minimal_flag_called_events && !flag.nil? && flag.has_experiment == false
+
+      @host.capture_flag_called_event_if_needed.call(
+        distinct_id: @distinct_id,
+        key: key,
+        response: response,
+        properties: properties,
+        groups: @groups,
+        disable_geoip: @disable_geoip,
+        minimal: minimal
+      )
+    end
+
+    def _clone_with(flags)
+      self.class.new(
+        host: @host,
+        distinct_id: @distinct_id,
+        flags: flags,
+        groups: @groups,
+        disable_geoip: @disable_geoip,
+        request_id: @request_id,
+        evaluated_at: @evaluated_at,
+        flag_definitions_loaded_at: @flag_definitions_loaded_at,
+        errors_while_computing: @errors_while_computing,
+        quota_limited: @quota_limited,
+        minimal_flag_called_events: @minimal_flag_called_events,
+        accessed: @accessed.dup
+      )
+    end
+  end
+end