txlemetry-ruby 4.0.0

data/lib/txlemetry/send_feature_flags_options.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'txlemetry/utils'
+
+module Txlemetry
+  # Options for configuring deprecated feature flag behavior in capture calls.
+  #
+  # @deprecated Prefer passing a {Txlemetry::FeatureFlagEvaluations} snapshot to `capture(flags:)`.
+  class SendFeatureFlagsOptions
+    # @return [Boolean, nil] Whether remote feature flag evaluation should be skipped.
+    attr_reader :only_evaluate_locally
+
+    # @return [Hash] Person properties to use for feature flag evaluation.
+    attr_reader :person_properties
+
+    # @return [Hash] Group properties to use for feature flag evaluation.
+    attr_reader :group_properties
+
+    # @param only_evaluate_locally [Boolean, nil] Skip remote feature flag evaluation.
+    # @param person_properties [Hash, nil] Person properties to use for feature flag evaluation.
+    # @param group_properties [Hash, nil] Group properties to use for feature flag evaluation.
+    def initialize(only_evaluate_locally: nil, person_properties: nil, group_properties: nil)
+      @only_evaluate_locally = only_evaluate_locally
+      @person_properties = person_properties || {}
+      @group_properties = group_properties || {}
+    end
+
+    # @return [Hash] A hash representation suitable for `capture(send_feature_flags:)`.
+    def to_h
+      {
+        only_evaluate_locally: @only_evaluate_locally,
+        person_properties: @person_properties,
+        group_properties: @group_properties
+      }
+    end
+
+    # @param hash [Hash]
+    # @return [Txlemetry::SendFeatureFlagsOptions, nil]
+    def self.from_hash(hash)
+      return nil unless hash.is_a?(Hash)
+
+      new(
+        only_evaluate_locally: Txlemetry::Utils.get_by_symbol_or_string_key(hash, :only_evaluate_locally),
+        person_properties: Txlemetry::Utils.get_by_symbol_or_string_key(hash, :person_properties),
+        group_properties: Txlemetry::Utils.get_by_symbol_or_string_key(hash, :group_properties)
+      )
+    end
+  end
+end

data/lib/txlemetry/send_worker.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'txlemetry/defaults'
+require 'txlemetry/message_batch'
+require 'txlemetry/transport'
+require 'txlemetry/utils'
+
+module Txlemetry
+  # Background worker that batches and sends queued events.
+  #
+  # @api private
+  class SendWorker
+    include Txlemetry::Utils
+    include Txlemetry::Defaults
+    include Txlemetry::Logging
+
+    # public: Creates a new worker
+    #
+    # The worker continuously takes messages off the queue
+    # and makes requests to the txlemetry.com api
+    #
+    # @param queue [Queue] Queue synchronized between client and worker.
+    # @param api_key [String] Project API key.
+    # @param options [Hash] Worker options.
+    # @option options [Integer] :batch_size How many items to send in a batch.
+    # @option options [Numeric] :flush_interval_seconds Maximum seconds to wait for a batch to fill before sending.
+    # @option options [Proc] :on_error Callback invoked as `on_error.call(status, error)`.
+    # @option options [String] :host Txlemetry API host URL.
+    # @option options [Boolean] :skip_ssl_verification Disable SSL certificate verification.
+    # @option options [Boolean] :compress_request Set to +false+ to disable gzip batch request bodies.
+    def initialize(queue, api_key, options = {})
+      symbolize_keys! options
+      @queue = queue
+      @api_key = api_key
+      @on_error = options[:on_error] || proc { |status, error| }
+      batch_size = options[:batch_size] || Defaults::MessageBatch::MAX_SIZE
+      flush_interval_seconds = options[:flush_interval_seconds] || Defaults::MessageBatch::FLUSH_INTERVAL_SECONDS
+      @flush_interval_seconds = flush_interval_seconds.to_f
+      @batch = MessageBatch.new(batch_size)
+      @lock = Mutex.new
+      @state_lock = Mutex.new
+      @condition = ConditionVariable.new
+      @flush_requested = false
+      @shutdown = false
+      @pid = Process.pid
+      @transport_options = {
+        api_host: options[:host],
+        headers: options[:headers],
+        skip_ssl_verification: options[:skip_ssl_verification],
+        compress_request: options[:compress_request]
+      }
+      @transport_options[:retries] = options[:max_retries].to_i + 1 if options.key?(:max_retries)
+      @transport = Transport.new(@transport_options)
+    end
+
+    # Continuously runs the loop to check for new events.
+    #
+    # @return [void]
+    def run
+      ensure_current_process!
+
+      until shutdown?
+        wait_for_work
+        break if shutdown?
+        next if @queue.empty?
+
+        build_batch
+
+        begin
+          send_batch unless @batch.empty?
+        ensure
+          @lock.synchronize { @batch.clear }
+          clear_flush_request_if_idle
+        end
+      end
+    ensure
+      shutdown_transport
+    end
+
+    # Request the worker to send any pending events without waiting for the
+    # configured flush interval. Used by Client#flush and shutdown paths.
+    #
+    # @return [void]
+    def request_flush
+      ensure_current_process!
+
+      @state_lock.synchronize do
+        @flush_requested = true
+        @condition.broadcast
+      end
+    end
+
+    # Wake the worker when producers enqueue new messages.
+    #
+    # @return [void]
+    def notify
+      ensure_current_process!
+
+      @state_lock.synchronize { @condition.signal }
+    end
+
+    # @return [void]
+    def shutdown
+      ensure_current_process!
+
+      @state_lock.synchronize do
+        @shutdown = true
+        @flush_requested = true
+        @condition.broadcast
+      end
+    end
+
+    # public: Check whether we have outstanding requests.
+    #
+    # @return [Boolean] Whether the worker has outstanding requests.
+    # TODO: Rename to `requesting?` in future version
+    def is_requesting? # rubocop:disable Naming/PredicatePrefix
+      ensure_current_process!
+
+      @lock.synchronize { !@batch.empty? }
+    end
+
+    private
+
+    def ensure_current_process!
+      return if @pid == Process.pid
+
+      @lock.synchronize { @batch.clear }
+      @state_lock.synchronize do
+        @pid = Process.pid
+        @shutdown = false
+        @flush_requested = false
+        @condition.broadcast
+      end
+      shutdown_transport
+      @transport = Transport.new(@transport_options)
+    end
+
+    def build_batch
+      deadline = monotonic_time + @flush_interval_seconds
+
+      loop do
+        @lock.synchronize do
+          consume_message_from_queue! until @batch.full? || @queue.empty?
+        end
+
+        break if @batch.full? || @batch.empty? || flush_requested?
+
+        remaining = deadline - monotonic_time
+        break unless remaining.positive?
+
+        wait_for_more_messages(remaining)
+      end
+    end
+
+    def send_batch
+      res = @transport.send @api_key, @batch
+      handle_error(res.status, res.error) unless res.status.between?(200, 299)
+    end
+
+    def consume_message_from_queue!
+      @batch << @queue.pop(true)
+    rescue ThreadError
+      # Queue was emptied by another thread between #empty? and #pop.
+    rescue MessageBatch::JSONGenerationError => e
+      handle_error(-1, e.to_s)
+    end
+
+    def wait_for_work
+      @state_lock.synchronize do
+        while @queue.empty? && !@shutdown
+          clear_flush_request_without_lock
+          @condition.wait(@state_lock)
+        end
+      end
+    end
+
+    def wait_for_more_messages(timeout)
+      @state_lock.synchronize do
+        return if @flush_requested || @shutdown || !@queue.empty?
+
+        @condition.wait(@state_lock, timeout)
+      end
+    end
+
+    def flush_requested?
+      @state_lock.synchronize { @flush_requested }
+    end
+
+    def shutdown?
+      @state_lock.synchronize { @shutdown }
+    end
+
+    def clear_flush_request
+      @state_lock.synchronize { clear_flush_request_without_lock }
+    end
+
+    def clear_flush_request_if_idle
+      @state_lock.synchronize { clear_flush_request_without_lock if @queue.empty? }
+    end
+
+    def clear_flush_request_without_lock
+      @flush_requested = false
+    end
+
+    def handle_error(status, error)
+      @on_error.call(status, error)
+    rescue StandardError => e
+      logger.error("Error in on_error callback: #{e.message}")
+    end
+
+    def shutdown_transport
+      @transport.shutdown
+    rescue StandardError => e
+      logger.error("Error shutting down transport: #{e.message}")
+    end
+  end
+end

data/lib/txlemetry/transport.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'txlemetry/defaults'
+require 'txlemetry/utils'
+require 'txlemetry/response'
+require 'txlemetry/logging'
+require 'txlemetry/backoff_policy'
+require 'net/http'
+require 'net/https'
+require 'json'
+require 'time'
+require 'zlib'
+
+module Txlemetry
+  # HTTP transport used by the SDK workers.
+  #
+  # @api private
+  class Transport
+    include Txlemetry::Defaults::Request
+    include Txlemetry::Utils
+    include Txlemetry::Logging
+
+    # @param options [Hash] Transport configuration.
+    # @option options [String] :api_host Full Txlemetry API host URL.
+    # @option options [String] :host Hostname to connect to.
+    # @option options [Integer] :port Port to connect to.
+    # @option options [Boolean] :ssl Whether to use HTTPS.
+    # @option options [Hash] :headers HTTP headers for batch requests.
+    # @option options [String] :path HTTP path for batch requests.
+    # @option options [Integer] :retries Number of retry attempts for retryable failures.
+    # @option options [Txlemetry::BackoffPolicy] :backoff_policy Backoff policy used between retries.
+    # @option options [Boolean] :skip_ssl_verification Disable SSL certificate verification.
+    # @option options [Boolean] :compress_request Whether to gzip batch request bodies. Defaults to +true+.
+    def initialize(options = {})
+      if options[:api_host]
+        uri = URI.parse(options[:api_host])
+        options[:host] = uri.host
+        options[:ssl] = uri.scheme == 'https'
+        options[:port] = uri.port
+      end
+
+      options[:host] = options[:host].nil? ? HOST : options[:host]
+      options[:port] = options[:port].nil? ? PORT : options[:port]
+      options[:ssl] = options[:ssl].nil? ? SSL : options[:ssl]
+
+      @headers = (options[:headers] || HEADERS).dup
+      @path = options[:path] || PATH
+      @retries = options[:retries] || RETRIES
+      @backoff_policy = options[:backoff_policy] || Txlemetry::BackoffPolicy.new
+      @compress_request = options[:compress_request] != false
+      @last_retry_after = nil
+
+      http = Net::HTTP.new(options[:host], options[:port])
+      http.use_ssl = options[:ssl]
+      http.read_timeout = 8
+      http.open_timeout = 4
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if options[:skip_ssl_verification]
+
+      @http = http
+      @http_mutex = Mutex.new
+    end
+
+    # Sends a batch of messages to the API
+    #
+    # @param api_key [String] Project API key.
+    # @param batch [Txlemetry::MessageBatch, Array<Hash>] Batch of messages to send.
+    # @return [Response] API response
+    def send(api_key, batch)
+      logger.debug("Sending request for #{batch.length} items")
+
+      last_response, exception =
+        retry_with_backoff(@retries) do
+          status_code, body = send_request(api_key, batch)
+          error =
+            begin
+              body && JSON.parse(body)['error']
+            rescue JSON::ParserError
+              body
+            end
+          should_retry = should_retry_request?(status_code, body)
+          logger.debug("Response status code: #{status_code}")
+          logger.debug("Response error: #{error}") if error
+
+          [Response.new(status_code, error), should_retry]
+        end
+
+      if exception
+        logger.error(exception.message)
+        exception.backtrace.each { |line| logger.error(line) }
+        Response.new(-1, exception.to_s)
+      else
+        last_response
+      end
+    end
+
+    # Closes a persistent connection if it exists.
+    #
+    # @return [void]
+    def shutdown
+      @http_mutex.synchronize do
+        @http.finish if @http.started?
+      end
+    end
+
+    private
+
+    def should_retry_request?(status_code, body)
+      if status_code >= 500 || [408, 429].include?(status_code)
+        true # Server error, request timeout, or rate limited
+      elsif status_code >= 400
+        logger.error(body)
+        false # Client error. Do not retry, but log
+      else
+        false
+      end
+    end
+
+    # Takes a block that returns [result, should_retry].
+    #
+    # Retries upto `retries_remaining` times, if `should_retry` is false or
+    # an exception is raised. `@backoff_policy` is used to determine the
+    # duration to sleep between attempts
+    #
+    # Returns [last_result, raised_exception]
+    def retry_with_backoff(retries_remaining, &block)
+      result, caught_exception = nil
+      should_retry = false
+
+      begin
+        result, should_retry = yield
+        return result, nil unless should_retry
+      rescue StandardError => e
+        should_retry = true
+        caught_exception = e
+      end
+
+      if should_retry && (retries_remaining > 1)
+        logger.debug("Retrying request, #{retries_remaining} retries left")
+        sleep(retry_delay_seconds)
+        retry_with_backoff(retries_remaining - 1, &block)
+      else
+        [result, caught_exception]
+      end
+    end
+
+    def retry_delay_seconds
+      retry_after = parse_retry_after(@last_retry_after)
+      @last_retry_after = nil
+      return retry_after if retry_after
+
+      @backoff_policy.next_interval.to_f / 1000
+    end
+
+    def parse_retry_after(value)
+      return nil if value.nil? || value.empty?
+
+      seconds = Float(value, exception: false)
+      return seconds if seconds && seconds >= 0
+
+      parsed_time = Time.httpdate(value)
+      delay = parsed_time - Time.now
+      delay.positive? ? delay : nil
+    rescue ArgumentError
+      nil
+    end
+
+    # Sends a request for the batch, returns [status_code, body]
+    def send_request(api_key, batch)
+      @last_retry_after = nil
+      payload = JSON.generate(api_key: api_key, batch: batch)
+
+      request_path, request_headers, request_payload = build_request(@path, @headers, payload)
+      request = Net::HTTP::Post.new(request_path, request_headers)
+
+      if self.class.stub
+        logger.debug "stubbed request to #{request_path}: " \
+                     "api key = #{api_key}, batch = #{JSON.generate(batch)}"
+
+        [200, '{}']
+      else
+        @http_mutex.synchronize do
+          @http.start unless @http.started? # Maintain a persistent connection
+          response = @http.request(request, request_payload)
+          @last_retry_after = response['Retry-After']
+          [response.code.to_i, response.body]
+        end
+      end
+    end
+
+    def build_request(path, headers, payload)
+      return [path, headers, payload] unless @compress_request
+
+      compressed_payload = gzip_payload(payload)
+      return [path, headers, payload] unless compressed_payload
+
+      compressed_headers = headers.merge('Content-Encoding' => 'gzip')
+
+      [path, compressed_headers, compressed_payload]
+    end
+
+    def gzip_payload(payload)
+      Zlib.gzip(payload)
+    rescue Zlib::Error => e
+      logger.warn("gzip compression failed; sending uncompressed - #{e.message}")
+      nil
+    end
+
+    class << self
+      attr_writer :stub
+
+      def stub
+        @stub || ENV.fetch('STUB', nil)
+      end
+    end
+  end
+end

data/lib/txlemetry/utils.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  class InconclusiveMatchError < StandardError
+  end
+
+  # Utility helpers used internally by the SDK.
+  #
+  # @api private
+  module Utils
+    module_function
+
+    # public: Return a new hash with keys converted from strings to symbols
+    #
+    def symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
+    end
+
+    # public: Convert hash keys from strings to symbols in place
+    #
+    def symbolize_keys!(hash)
+      hash.replace symbolize_keys hash
+    end
+
+    # public: Return a new hash with keys as strings
+    #
+    def stringify_keys(hash)
+      hash.transform_keys(&:to_s)
+    end
+
+    # public: Recursively convert all keys to symbols in a Hash/Array tree
+    #
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = deep_symbolize_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_symbolize_keys(item) }
+      else
+        obj
+      end
+    end
+
+    # public: Returns a new hash with all the date values in the into iso8601
+    #         strings
+    #
+    def isoify_dates(hash)
+      hash.transform_values do |v|
+        datetime_in_iso8601(v)
+      end
+    end
+
+    # public: Converts all the date values in the into iso8601 strings in place
+    #
+    def isoify_dates!(hash)
+      hash.replace isoify_dates hash
+    end
+
+    def datetime_in_iso8601(datetime)
+      case datetime
+      when Time
+        time_in_iso8601 datetime
+      when DateTime
+        time_in_iso8601 datetime.to_time
+      when Date
+        date_in_iso8601 datetime
+      else
+        datetime
+      end
+    end
+
+    def time_in_iso8601(time, fraction_digits = 3)
+      fraction =
+        (('.%06i' % time.usec)[0, fraction_digits + 1] if fraction_digits.positive?) # rubocop:disable Style/FormatString
+
+      "#{time.strftime('%Y-%m-%dT%H:%M:%S')}#{fraction}#{formatted_offset(time, true, 'Z')}"
+    end
+
+    def date_in_iso8601(date)
+      date.strftime('%F')
+    end
+
+    def formatted_offset(time, colon = true, alternate_utc_string = nil)
+      (time.utc? && alternate_utc_string) ||
+        seconds_to_utc_offset(time.utc_offset, colon)
+    end
+
+    def seconds_to_utc_offset(seconds, colon = true)
+      format((colon ? UTC_OFFSET_WITH_COLON : UTC_OFFSET_WITHOUT_COLON), (seconds.negative? ? '-' : '+'),
+             seconds.abs / 3600, (seconds.abs % 3600) / 60)
+    end
+
+    def convert_to_datetime(value)
+      if value.respond_to?(:strftime)
+        value
+
+      elsif value.respond_to?(:to_str)
+        begin
+          DateTime.parse(value)
+        rescue ArgumentError
+          raise InconclusiveMatchError, "#{value} is not in a valid date format"
+        end
+      else
+        raise InconclusiveMatchError, 'The date provided must be a string or date object'
+      end
+    end
+
+    UTC_OFFSET_WITH_COLON = '%s%02d:%02d'
+    UTC_OFFSET_WITHOUT_COLON = UTC_OFFSET_WITH_COLON.sub(':', '')
+
+    # TODO: Rename to `valid_regex?` in future version
+    def is_valid_regex(regex) # rubocop:disable Naming/PredicatePrefix
+      Regexp.new(regex)
+      true
+    rescue RegexpError
+      false
+    end
+
+    # public: Get value from hash by symbol key first, then string key
+    #         Handles falsy values correctly (unlike ||)
+    #
+    # hash - Hash to lookup value in
+    # key  - Symbol or String key to lookup
+    #
+    # Returns the value if found, nil otherwise
+    def get_by_symbol_or_string_key(hash, key)
+      symbol_key = key.to_sym
+      string_key = key.to_s
+
+      if hash.key?(symbol_key)
+        hash[symbol_key]
+      else
+        hash[string_key]
+      end
+    end
+
+    # public: Current monotonic clock time in seconds, for measuring durations
+    #
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Hash that clears itself when it reaches a maximum length.
+    #
+    # @api private
+    class SizeLimitedHash < Hash
+      # @param max_length [Integer]
+      def initialize(max_length, ...)
+        super(...)
+        @max_length = max_length
+      end
+
+      # @param key [Object]
+      # @param value [Object]
+      # @return [Object]
+      def []=(key, value)
+        clear if length >= @max_length
+        super
+      end
+    end
+
+    # Array that drops the oldest item when it reaches a maximum length.
+    #
+    # @api private
+    class SizeLimitedArray < Array
+      # @param max_length [Integer]
+      def initialize(max_length)
+        super()
+        @max_length = max_length
+      end
+
+      # @param value [Object]
+      # @return [Array]
+      def <<(value)
+        shift if length >= @max_length
+        super
+      end
+    end
+    private_constant :SizeLimitedArray
+  end
+end

data/lib/txlemetry/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  VERSION = '4.0.0'
+end

data/lib/txlemetry.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'txlemetry/version'
+require 'txlemetry/defaults'
+require 'txlemetry/utils'
+require 'txlemetry/field_parser'
+require 'txlemetry/client'
+require 'txlemetry/send_worker'
+require 'txlemetry/transport'
+require 'txlemetry/response'
+require 'txlemetry/logging'
+require 'txlemetry/exception_capture'
+require 'txlemetry/feature_flag_error'
+require 'txlemetry/feature_flag_result'
+require 'txlemetry/feature_flag_evaluations'
+require 'txlemetry/flag_definition_cache'