posthog-rails 3.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c928e33ae64462619dd81b5b785402c17f4cc5ebba9d7858cb33d7b38b426d4a
+  data.tar.gz: 5ee1084fde161538e21b53f257bc485aa9fafc0b6b4549776a28ab5d56c2de7a
+SHA512:
+  metadata.gz: 3e3cc76336d84ab77d948e5a0504694926565bec21f8b535d70e5eb6671449b0676e60677f9257170b5e84c703e351baf9fe35ee091544df26859fdba7210f4c
+  data.tar.gz: 54d4dd5aee80aa5f85961672934cb7c565e16342327678f9352ed7ed6e9d484479418585ef4e9cbf39eed6e00063290c2a9e253f50621796f8e50774c97a5ade

data/lib/posthog/backoff_policy.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'posthog/defaults'
+
+module PostHog
+  class BackoffPolicy
+    include PostHog::Defaults::BackoffPolicy
+
+    # @param [Hash] opts
+    # @option opts [Numeric] :min_timeout_ms The minimum backoff timeout
+    # @option opts [Numeric] :max_timeout_ms The maximum backoff timeout
+    # @option opts [Numeric] :multiplier The value to multiply the current
+    #   interval with for each retry attempt
+    # @option opts [Numeric] :randomization_factor The randomization factor
+    #   to use to create a range around the retry interval
+    def initialize(opts = {})
+      @min_timeout_ms = opts[:min_timeout_ms] || MIN_TIMEOUT_MS
+      @max_timeout_ms = opts[:max_timeout_ms] || MAX_TIMEOUT_MS
+      @multiplier = opts[:multiplier] || MULTIPLIER
+      @randomization_factor =
+        opts[:randomization_factor] || RANDOMIZATION_FACTOR
+
+      @attempts = 0
+    end
+
+    # @return [Numeric] the next backoff interval, in milliseconds.
+    def next_interval
+      interval = @min_timeout_ms * (@multiplier**@attempts)
+      interval = add_jitter(interval, @randomization_factor)
+
+      @attempts += 1
+
+      [interval, @max_timeout_ms].min
+    end
+
+    private
+
+    def add_jitter(base, randomization_factor)
+      random_number = rand
+      max_deviation = base * randomization_factor
+      deviation = random_number * max_deviation
+
+      random_number < 0.5 ? base - deviation : base + deviation
+    end
+  end
+end

data/lib/posthog/client.rb

@@ -0,0 +1,545 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'securerandom'
+
+require 'posthog/defaults'
+require 'posthog/logging'
+require 'posthog/utils'
+require 'posthog/send_worker'
+require 'posthog/noop_worker'
+require 'posthog/feature_flags'
+require 'posthog/send_feature_flags_options'
+require 'posthog/exception_capture'
+
+module PostHog
+  class Client
+    include PostHog::Utils
+    include PostHog::Logging
+
+    # @param [Hash] opts
+    # @option opts [String] :api_key Your project's api_key
+    # @option opts [String] :personal_api_key Your personal API key
+    # @option opts [FixNum] :max_queue_size Maximum number of calls to be
+    #   remain queued. Defaults to 10_000.
+    # @option opts [Bool] :test_mode +true+ if messages should remain
+    #   queued for testing. Defaults to +false+.
+    # @option opts [Proc] :on_error Handles error calls from the API.
+    # @option opts [String] :host Fully qualified hostname of the PostHog server. Defaults to `https://app.posthog.com`
+    # @option opts [Integer] :feature_flags_polling_interval How often to poll for feature flag definition changes.
+    #   Measured in seconds, defaults to 30.
+    # @option opts [Integer] :feature_flag_request_timeout_seconds How long to wait for feature flag evaluation.
+    #   Measured in seconds, defaults to 3.
+    # @option opts [Proc] :before_send A block that receives the event hash and should return either a modified hash
+    #   to be sent to PostHog or nil to prevent the event from being sent. e.g. `before_send: ->(event) { event }`
+    def initialize(opts = {})
+      symbolize_keys!(opts)
+
+      opts[:host] ||= 'https://app.posthog.com'
+
+      @queue = Queue.new
+      @api_key = opts[:api_key]
+      @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
+      @worker_mutex = Mutex.new
+      @worker = if opts[:test_mode]
+                  NoopWorker.new(@queue)
+                else
+                  SendWorker.new(@queue, @api_key, opts)
+                end
+      @worker_thread = nil
+      @feature_flags_poller = nil
+      @personal_api_key = opts[:personal_api_key]
+
+      check_api_key!
+
+      @feature_flags_poller =
+        FeatureFlagsPoller.new(
+          opts[:feature_flags_polling_interval],
+          opts[:personal_api_key],
+          @api_key,
+          opts[:host],
+          opts[:feature_flag_request_timeout_seconds] || Defaults::FeatureFlags::FLAG_REQUEST_TIMEOUT_SECONDS,
+          opts[:on_error]
+        )
+
+      @distinct_id_has_sent_flag_calls = SizeLimitedHash.new(Defaults::MAX_HASH_SIZE) do |hash, key|
+        hash[key] = []
+      end
+
+      @before_send = opts[:before_send]
+    end
+
+    # Synchronously waits until the worker has cleared the queue.
+    #
+    # Use only for scripts which are not long-running, and will specifically
+    # exit
+    def flush
+      while !@queue.empty? || @worker.is_requesting?
+        ensure_worker_running
+        sleep(0.1)
+      end
+    end
+
+    # Clears the queue without waiting.
+    #
+    # Use only in test mode
+    def clear
+      @queue.clear
+    end
+
+    # @!macro common_attrs
+    #   @option attrs [String] :message_id ID that uniquely
+    #     identifies a message across the API. (optional)
+    #   @option attrs [Time] :timestamp When the event occurred (optional)
+    #   @option attrs [String] :distinct_id The ID for this user in your database
+
+    # Captures an event
+    #
+    # @param [Hash] attrs
+    #
+    # @option attrs [String] :event Event name
+    # @option attrs [Hash] :properties Event properties (optional)
+    # @option attrs [Bool, Hash, SendFeatureFlagsOptions] :send_feature_flags
+    #   Whether to send feature flags with this event, or configuration for feature flag evaluation (optional)
+    # @option attrs [String] :uuid ID that uniquely identifies an event;
+    #                             events in PostHog are deduplicated by the
+    #                             combination of teamId, timestamp date,
+    #                             event name, distinct id, and UUID
+    # @macro common_attrs
+    def capture(attrs)
+      symbolize_keys! attrs
+
+      send_feature_flags_param = attrs[:send_feature_flags]
+      if send_feature_flags_param
+        # Handle different types of send_feature_flags parameter
+        case send_feature_flags_param
+        when true
+          # Backward compatibility: simple boolean
+          feature_variants = @feature_flags_poller.get_feature_variants(attrs[:distinct_id], attrs[:groups] || {})
+        when Hash
+          # Hash with options
+          options = SendFeatureFlagsOptions.from_hash(send_feature_flags_param)
+          feature_variants = @feature_flags_poller.get_feature_variants(
+            attrs[:distinct_id],
+            attrs[:groups] || {},
+            options ? options.person_properties : {},
+            options ? options.group_properties : {},
+            options ? options.only_evaluate_locally : false
+          )
+        when SendFeatureFlagsOptions
+          # SendFeatureFlagsOptions object
+          feature_variants = @feature_flags_poller.get_feature_variants(
+            attrs[:distinct_id],
+            attrs[:groups] || {},
+            send_feature_flags_param.person_properties,
+            send_feature_flags_param.group_properties,
+            send_feature_flags_param.only_evaluate_locally || false
+          )
+        else
+          # Invalid type, treat as false
+          feature_variants = nil
+        end
+
+        attrs[:feature_variants] = feature_variants if feature_variants
+      end
+
+      enqueue(FieldParser.parse_for_capture(attrs))
+    end
+
+    # Captures an exception as an event
+    #
+    # @param [Exception, String, Object] exception The exception to capture, a string message, or exception-like object
+    # @param [String] distinct_id The ID for the user (optional, defaults to a generated UUID)
+    # @param [Hash] additional_properties Additional properties to include with the exception event (optional)
+    def capture_exception(exception, distinct_id = nil, additional_properties = {})
+      exception_info = ExceptionCapture.build_parsed_exception(exception)
+
+      return if exception_info.nil?
+
+      no_distinct_id_was_provided = distinct_id.nil?
+      distinct_id ||= SecureRandom.uuid
+
+      properties = { '$exception_list' => [exception_info] }
+      properties.merge!(additional_properties) if additional_properties && !additional_properties.empty?
+      properties['$process_person_profile'] = false if no_distinct_id_was_provided
+
+      event_data = {
+        distinct_id: distinct_id,
+        event: '$exception',
+        properties: properties,
+        timestamp: Time.now
+      }
+
+      capture(event_data)
+    end
+
+    # Identifies a user
+    #
+    # @param [Hash] attrs
+    #
+    # @option attrs [Hash] :properties User properties (optional)
+    # @macro common_attrs
+    def identify(attrs)
+      symbolize_keys! attrs
+      enqueue(FieldParser.parse_for_identify(attrs))
+    end
+
+    # Identifies a group
+    #
+    # @param [Hash] attrs
+    #
+    # @option attrs [String] :group_type Group type
+    # @option attrs [String] :group_key Group key
+    # @option attrs [Hash] :properties Group properties (optional)
+    # @option attrs [String] :distinct_id Distinct ID (optional)
+    # @macro common_attrs
+    def group_identify(attrs)
+      symbolize_keys! attrs
+      enqueue(FieldParser.parse_for_group_identify(attrs))
+    end
+
+    # Aliases a user from one id to another
+    #
+    # @param [Hash] attrs
+    #
+    # @option attrs [String] :alias The alias to give the distinct id
+    # @macro common_attrs
+    def alias(attrs)
+      symbolize_keys! attrs
+      enqueue(FieldParser.parse_for_alias(attrs))
+    end
+
+    # @return [Hash] pops the last message from the queue
+    def dequeue_last_message
+      @queue.pop
+    end
+
+    # @return [Fixnum] number of messages in the queue
+    def queued_messages
+      @queue.length
+    end
+
+    # TODO: In future version, rename to `feature_flag_enabled?`
+    def is_feature_enabled( # rubocop:disable Naming/PredicateName
+      flag_key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      response = get_feature_flag(
+        flag_key,
+        distinct_id,
+        groups: groups,
+        person_properties: person_properties,
+        group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally,
+        send_feature_flag_events: send_feature_flag_events
+      )
+      return nil if response.nil?
+
+      !!response
+    end
+
+    # @param [String] flag_key The unique flag key of the feature flag
+    # @return [String] The decrypted value of the feature flag payload
+    def get_remote_config_payload(flag_key)
+      @feature_flags_poller.get_remote_config_payload(flag_key)
+    end
+
+    # Returns whether the given feature flag is enabled for the given user or not
+    #
+    # @param [String] key The key of the feature flag
+    # @param [String] distinct_id The distinct id of the user
+    # @param [Hash] groups
+    # @param [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @param [Hash] group_properties
+    #
+    # @return [String, nil] The value of the feature flag
+    #
+    # The provided properties are used to calculate feature flags locally, if possible.
+    #
+    # `groups` are a mapping from group type to group key. So, if you have a group type of "organization"
+    # and a group key of "5",
+    # you would pass groups={"organization": "5"}.
+    # `group_properties` take the format: { group_type_name: { group_properties } }
+    # So, for example, if you have the group type "organization" and the group key "5", with the properties name,
+    # and employee count, you'll send these as:
+    # ```ruby
+    #     group_properties: {"organization": {"name": "PostHog", "employees": 11}}
+    # ```
+    def get_feature_flag(
+      key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      result = get_feature_flag_result(
+        key,
+        distinct_id,
+        groups: groups,
+        person_properties: person_properties,
+        group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally,
+        send_feature_flag_events: send_feature_flag_events
+      )
+      result&.value
+    end
+
+    # Returns both the feature flag value and payload in a single call.
+    # This method raises the $feature_flag_called event with the payload included.
+    #
+    # @param [String] key The key of the feature flag
+    # @param [String] distinct_id The distinct id of the user
+    # @param [Hash] groups
+    # @param [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @param [Hash] group_properties
+    # @param [Boolean] only_evaluate_locally
+    # @param [Boolean] send_feature_flag_events
+    #
+    # @return [FeatureFlagResult, nil] A FeatureFlagResult object containing the flag value and payload,
+    #   or nil if the flag evaluation returned nil
+    def get_feature_flag_result(
+      key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      person_properties, group_properties = add_local_person_and_group_properties(
+        distinct_id,
+        groups,
+        person_properties,
+        group_properties
+      )
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload =
+        @feature_flags_poller.get_feature_flag(
+          key,
+          distinct_id,
+          groups,
+          person_properties,
+          group_properties,
+          only_evaluate_locally
+        )
+      feature_flag_reported_key = "#{key}_#{feature_flag_response}"
+
+      if !@distinct_id_has_sent_flag_calls[distinct_id].include?(feature_flag_reported_key) && send_feature_flag_events
+        properties = {
+          '$feature_flag' => key,
+          '$feature_flag_response' => feature_flag_response,
+          'locally_evaluated' => flag_was_locally_evaluated
+        }
+        properties['$feature_flag_request_id'] = request_id if request_id
+        properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
+        properties['$feature_flag_error'] = feature_flag_error if feature_flag_error
+
+        capture(
+          distinct_id: distinct_id,
+          event: '$feature_flag_called',
+          properties: properties,
+          groups: groups
+        )
+        @distinct_id_has_sent_flag_calls[distinct_id] << feature_flag_reported_key
+      end
+
+      FeatureFlagResult.from_value_and_payload(key, feature_flag_response, payload)
+    end
+
+    # Returns all flags for a given user
+    #
+    # @param [String] distinct_id The distinct id of the user
+    # @param [Hash] groups
+    # @param [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @param [Hash] group_properties
+    #
+    # @return [Hash] String (not symbol) key value pairs of flag and their values
+    def get_all_flags(
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false
+    )
+      person_properties, group_properties = add_local_person_and_group_properties(distinct_id, groups,
+                                                                                  person_properties, group_properties)
+      @feature_flags_poller.get_all_flags(distinct_id, groups, person_properties, group_properties,
+                                          only_evaluate_locally)
+    end
+
+    # Returns payload for a given feature flag
+    #
+    # @deprecated Use {#get_feature_flag_result} instead, which returns both the flag value and payload
+    #   and properly raises the $feature_flag_called event.
+    #
+    # @param [String] key The key of the feature flag
+    # @param [String] distinct_id The distinct id of the user
+    # @option [String or boolean] match_value The value of the feature flag to be matched
+    # @option [Hash] groups
+    # @option [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @option [Hash] group_properties
+    # @option [Boolean] only_evaluate_locally
+    #
+    def get_feature_flag_payload(
+      key,
+      distinct_id,
+      match_value: nil,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false
+    )
+      person_properties, group_properties = add_local_person_and_group_properties(distinct_id, groups,
+                                                                                  person_properties, group_properties)
+      @feature_flags_poller.get_feature_flag_payload(key, distinct_id, match_value, groups, person_properties,
+                                                     group_properties, only_evaluate_locally)
+    end
+
+    # Returns all flags and payloads for a given user
+    #
+    # @return [Hash] A hash with the following keys:
+    #   featureFlags: A hash of feature flags
+    #   featureFlagPayloads: A hash of feature flag payloads
+    #
+    # @param [String] distinct_id The distinct id of the user
+    # @option [Hash] groups
+    # @option [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @option [Hash] group_properties
+    # @option [Boolean] only_evaluate_locally
+    #
+    def get_all_flags_and_payloads(
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false
+    )
+      person_properties, group_properties = add_local_person_and_group_properties(
+        distinct_id, groups, person_properties, group_properties
+      )
+      response = @feature_flags_poller.get_all_flags_and_payloads(
+        distinct_id, groups, person_properties, group_properties, only_evaluate_locally
+      )
+
+      # Remove internal information
+      response.delete(:requestId)
+      response.delete(:evaluatedAt)
+      response
+    end
+
+    def reload_feature_flags
+      unless @personal_api_key
+        logger.error(
+          'You need to specify a personal_api_key to locally evaluate feature flags'
+        )
+        return
+      end
+      @feature_flags_poller.load_feature_flags(true)
+    end
+
+    def shutdown
+      @feature_flags_poller.shutdown_poller
+      flush
+    end
+
+    private
+
+    # before_send should run immediately before the event is sent to the queue.
+    # @param [Object] action The event to be sent to PostHog
+    # @return [null, Object, nil] The processed event or nil if the event should not be sent
+    def process_before_send(action)
+      return action if action.nil? || action.empty?
+      return action unless @before_send
+
+      begin
+        processed_action = @before_send.call(action)
+
+        if processed_action.nil?
+          logger.warn("Event #{action[:event]} was rejected in beforeSend function")
+        elsif processed_action.empty?
+          logger.warn("Event #{action[:event]} has no properties after beforeSend function, this is likely an error")
+        end
+
+        processed_action
+      rescue StandardError => e
+        logger.error("Error in beforeSend function - using original event: #{e.message}")
+        action
+      end
+    end
+
+    # private: Enqueues the action.
+    #
+    # returns Boolean of whether the item was added to the queue.
+    def enqueue(action)
+      action = process_before_send(action)
+      return false if action.nil? || action.empty?
+
+      # add our request id for tracing purposes
+      action[:messageId] ||= uid
+
+      if @queue.length < @max_queue_size
+        @queue << action
+        ensure_worker_running
+
+        true
+      else
+        logger.warn(
+          'Queue is full, dropping events. The :max_queue_size ' \
+          'configuration parameter can be increased to prevent this from ' \
+          'happening.'
+        )
+        false
+      end
+    end
+
+    # private: Checks that the api_key is properly initialized
+    def check_api_key!
+      raise ArgumentError, 'API key must be initialized' if @api_key.nil?
+    end
+
+    def ensure_worker_running
+      return if worker_running?
+
+      @worker_mutex.synchronize do
+        return if worker_running?
+
+        @worker_thread = Thread.new { @worker.run }
+      end
+    end
+
+    def worker_running?
+      @worker_thread&.alive?
+    end
+
+    def add_local_person_and_group_properties(distinct_id, groups, person_properties, group_properties)
+      groups ||= {}
+      person_properties ||= {}
+      group_properties ||= {}
+
+      symbolize_keys! groups
+      symbolize_keys! person_properties
+      symbolize_keys! group_properties
+
+      group_properties.each_value do |value|
+        symbolize_keys! value
+      end
+
+      all_person_properties = { distinct_id: distinct_id }.merge(person_properties)
+
+      all_group_properties = {}
+      groups&.each do |group_name, group_key|
+        all_group_properties[group_name] = {
+          '$group_key': group_key
+        }.merge((group_properties && group_properties[group_name]) || {})
+      end
+
+      [all_person_properties, all_group_properties]
+    end
+  end
+end

data/lib/posthog/defaults.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PostHog
+  module Defaults
+    MAX_HASH_SIZE = 50_000
+
+    module Request
+      HOST = 'app.posthog.com'
+      PORT = 443
+      PATH = '/batch/'
+      SSL = true
+      HEADERS = {
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+        'User-Agent' => "posthog-ruby/#{PostHog::VERSION}"
+      }.freeze
+      RETRIES = 10
+    end
+
+    module FeatureFlags
+      FLAG_REQUEST_TIMEOUT_SECONDS = 3
+    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
+    end
+
+    module BackoffPolicy
+      MIN_TIMEOUT_MS = 100
+      MAX_TIMEOUT_MS = 10_000
+      MULTIPLIER = 1.5
+      RANDOMIZATION_FACTOR = 0.5
+    end
+  end
+end