posthog-rails 3.5.0

data/lib/posthog/field_parser.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'posthog/logging'
+
+module PostHog
+  class FieldParser
+    class << self
+      include PostHog::Utils
+      include PostHog::Logging
+
+      # In addition to the common fields, capture accepts:
+      #
+      # - "event"
+      # - "properties"
+      # - "groups"
+      # - "uuid"
+      def parse_for_capture(fields)
+        common = parse_common_fields(fields)
+
+        event = fields[:event]
+        properties = fields[:properties] || {}
+        groups = fields[:groups]
+        uuid = fields[:uuid]
+        check_presence!(event, 'event')
+        check_is_hash!(properties, 'properties')
+
+        if groups
+          check_is_hash!(groups, 'groups')
+          properties['$groups'] = groups
+        end
+
+        isoify_dates! properties
+
+        common['uuid'] = uuid if valid_uuid_for_event_props? uuid
+
+        common.merge(
+          {
+            type: 'capture',
+            event: event.to_s,
+            properties: properties.merge(common[:properties] || {})
+          }
+        )
+      end
+
+      # In addition to the common fields, identify accepts:
+      #
+      # - "properties"
+      def parse_for_identify(fields)
+        common = parse_common_fields(fields)
+
+        properties = fields[:properties] || {}
+        check_is_hash!(properties, 'properties')
+
+        isoify_dates! properties
+
+        common.merge(
+          {
+            type: 'identify',
+            event: '$identify',
+            '$set': properties,
+            properties: properties.merge(common[:properties] || {})
+          }
+        )
+      end
+
+      def parse_for_group_identify(fields)
+        properties = fields[:properties] || {}
+        group_type = fields[:group_type]
+        group_key = fields[:group_key]
+
+        check_presence!(group_type, 'group type')
+        check_presence!(group_key, 'group_key')
+        check_is_hash!(properties, 'properties')
+
+        fields[:distinct_id] ||= "$#{group_type}_#{group_key}"
+        common = parse_common_fields(fields)
+
+        isoify_dates! properties
+
+        common.merge(
+          {
+            event: '$groupidentify',
+            properties: {
+              '$group_type': group_type,
+              '$group_key': group_key,
+              '$group_set': properties.merge(common[:properties] || {})
+            }
+          }
+        )
+      end
+
+      # In addition to the common fields, alias accepts:
+      #
+      # - "alias"
+      def parse_for_alias(fields)
+        common = parse_common_fields(fields)
+
+        distinct_id = common[:distinct_id] # must both be set and move to properties
+
+        alias_field = fields[:alias]
+        check_presence! alias_field, 'alias'
+
+        common.merge(
+          {
+            type: 'alias',
+            event: '$create_alias',
+            distinct_id: distinct_id,
+            properties:
+              { distinct_id: distinct_id, alias: alias_field }.merge(
+                common[:properties] || {}
+              )
+          }
+        )
+      end
+
+      private
+
+      # Common fields are:
+      #
+      # - "timestamp"
+      # - "distinct_id"
+      # - "message_id"
+      # - "send_feature_flags"
+      def parse_common_fields(fields)
+        timestamp = fields[:timestamp] || Time.new
+        distinct_id = fields[:distinct_id]
+        message_id = fields[:message_id].to_s if fields[:message_id]
+        send_feature_flags = fields[:send_feature_flags]
+
+        check_timestamp! timestamp
+        check_presence! distinct_id, 'distinct_id'
+
+        parsed = {
+          timestamp: datetime_in_iso8601(timestamp),
+          library: 'posthog-ruby',
+          library_version: PostHog::VERSION.to_s,
+          messageId: message_id,
+          distinct_id: distinct_id,
+          properties: {
+            '$lib' => 'posthog-ruby',
+            '$lib_version' => PostHog::VERSION.to_s
+          }
+        }
+
+        if send_feature_flags && fields[:feature_variants]
+          feature_variants = fields[:feature_variants]
+          active_feature_variants = {}
+          feature_variants.each do |key, value|
+            parsed[:properties]["$feature/#{key}"] = value
+            active_feature_variants[key] = value if value != false
+          end
+          parsed[:properties]['$active_feature_flags'] = active_feature_variants.keys
+        end
+        parsed
+      end
+
+      def check_timestamp!(timestamp)
+        return if timestamp.is_a? Time
+
+        raise ArgumentError, 'Timestamp must be a Time'
+      end
+
+      # private: Ensures that a string is non-empty
+      #
+      # obj    - String|Number that must be not blank
+      # name   - The name of the validated value
+      def check_presence!(obj, name)
+        return unless obj.nil? || (obj.is_a?(String) && obj.empty?)
+
+        raise ArgumentError, "#{name} must be given"
+      end
+
+      def check_is_hash!(obj, name)
+        raise ArgumentError, "#{name} must be a Hash" unless obj.is_a? Hash
+      end
+
+      # @param [Object] uuid - the UUID to validate, user provided, so we don't know the type
+      # @return [TrueClass, FalseClass] - true if the UUID is valid or absent, false otherwise
+      def valid_uuid_for_event_props?(uuid)
+        return true if uuid.nil?
+
+        unless uuid.is_a?(String)
+          logger.warn 'UUID is not a string. Ignoring it.'
+          return false
+        end
+
+        is_valid_uuid = uuid.match?(/^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$/i)
+        logger.warn "UUID is not valid: #{uuid}. Ignoring it." unless is_valid_uuid
+
+        is_valid_uuid
+      end
+    end
+  end
+end

data/lib/posthog/logging.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module PostHog
+  # Wraps an existing logger and adds a prefix to all messages
+  class PrefixedLogger
+    def initialize(logger, prefix)
+      @logger = logger
+      @prefix = prefix
+    end
+
+    def debug(msg)
+      @logger.debug("#{@prefix} #{msg}")
+    end
+
+    def info(msg)
+      @logger.info("#{@prefix} #{msg}")
+    end
+
+    def warn(msg)
+      @logger.warn("#{@prefix} #{msg}")
+    end
+
+    def error(msg)
+      @logger.error("#{@prefix} #{msg}")
+    end
+
+    def level=(severity)
+      @logger.level = severity
+    end
+
+    def level
+      @logger.level
+    end
+  end
+
+  module Logging
+    class << self
+      def logger
+        return @logger if @logger
+
+        base_logger =
+          if defined?(::Rails)
+            ::Rails.logger
+          else
+            logger = Logger.new $stdout
+            logger.progname = 'PostHog'
+            logger.level = Logger::WARN
+            logger
+          end
+        @logger = PrefixedLogger.new(base_logger, '[posthog-ruby]')
+      end
+
+      attr_writer :logger
+    end
+
+    def self.included(base)
+      class << base
+        def logger
+          Logging.logger
+        end
+      end
+    end
+
+    def logger
+      Logging.logger
+    end
+  end
+end

data/lib/posthog/message_batch.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'posthog/logging'
+
+module PostHog
+  # A batch of `Message`s to be sent to the API
+  class MessageBatch
+    class JSONGenerationError < StandardError
+    end
+
+    extend Forwardable
+    include PostHog::Logging
+    include PostHog::Defaults::MessageBatch
+
+    def initialize(max_message_count)
+      @messages = []
+      @max_message_count = max_message_count
+      @json_size = 0
+    end
+
+    def <<(message)
+      begin
+        message_json = message.to_json
+      rescue StandardError => e
+        raise JSONGenerationError, "Serialization error: #{e}"
+      end
+
+      message_json_size = message_json.bytesize
+      if message_too_big?(message_json_size)
+        logger.error('a message exceeded the maximum allowed size')
+      else
+        @messages << message
+        @json_size += message_json_size + 1 # One byte for the comma
+      end
+    end
+
+    def full?
+      item_count_exhausted? || size_exhausted?
+    end
+
+    def clear
+      @messages.clear
+      @json_size = 0
+    end
+
+    def_delegators :@messages, :to_json
+    def_delegators :@messages, :empty?
+    def_delegators :@messages, :length
+
+    private
+
+    def item_count_exhausted?
+      @messages.length >= @max_message_count
+    end
+
+    def message_too_big?(message_json_size)
+      message_json_size > Defaults::Message::MAX_BYTES
+    end
+
+    # We consider the max size here as just enough to leave room for one more
+    # message of the largest size possible. This is a shortcut that allows us
+    # to use a native Ruby `Queue` that doesn't allow peeking. The tradeoff
+    # here is that we might fit in less messages than possible into a batch.
+    #
+    # The alternative is to use our own `Queue` implementation that allows
+    # peeking, and to consider the next message size when calculating whether
+    # the message can be accomodated in this batch.
+    def size_exhausted?
+      @json_size >= (MAX_BYTES - Defaults::Message::MAX_BYTES)
+    end
+  end
+end

data/lib/posthog/noop_worker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# A worker that doesn't consume jobs
+module PostHog
+  class NoopWorker
+    def initialize(queue)
+      @queue = queue
+    end
+
+    def run
+      # Does nothing
+    end
+
+    # TODO: Rename to `requesting?` in future version
+    def is_requesting? # rubocop:disable Naming/PredicateName
+      false
+    end
+  end
+end

data/lib/posthog/response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PostHog
+  class Response
+    attr_reader :status, :error
+
+    # public: Simple class to wrap responses from the API
+    #
+    #
+    def initialize(status = 200, error = nil)
+      @status = status
+      @error = error
+    end
+  end
+end

data/lib/posthog/send_feature_flags_options.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'posthog/utils'
+
+module PostHog
+  # Options for configuring feature flag behavior in capture calls
+  class SendFeatureFlagsOptions
+    attr_reader :only_evaluate_locally, :person_properties, :group_properties
+
+    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
+
+    def to_h
+      {
+        only_evaluate_locally: @only_evaluate_locally,
+        person_properties: @person_properties,
+        group_properties: @group_properties
+      }
+    end
+
+    def self.from_hash(hash)
+      return nil unless hash.is_a?(Hash)
+
+      new(
+        only_evaluate_locally: PostHog::Utils.get_by_symbol_or_string_key(hash, :only_evaluate_locally),
+        person_properties: PostHog::Utils.get_by_symbol_or_string_key(hash, :person_properties),
+        group_properties: PostHog::Utils.get_by_symbol_or_string_key(hash, :group_properties)
+      )
+    end
+  end
+end

data/lib/posthog/send_worker.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'posthog/defaults'
+require 'posthog/message_batch'
+require 'posthog/transport'
+require 'posthog/utils'
+
+module PostHog
+  class SendWorker
+    include PostHog::Utils
+    include PostHog::Defaults
+    include PostHog::Logging
+
+    # public: Creates a new worker
+    #
+    # The worker continuously takes messages off the queue
+    # and makes requests to the posthog.com api
+    #
+    # queue   - Queue synchronized between client and worker
+    # api_key  - String of the project's API key
+    # options - Hash of worker options
+    #           batch_size - Fixnum of how many items to send in a batch
+    #           on_error   - Proc of what to do on an error
+    #
+    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
+      @batch = MessageBatch.new(batch_size)
+      @lock = Mutex.new
+      @transport = Transport.new api_host: options[:host], skip_ssl_verification: options[:skip_ssl_verification]
+    end
+
+    # public: Continuously runs the loop to check for new events
+    #
+    def run
+      until Thread.current[:should_exit]
+        return if @queue.empty?
+
+        @lock.synchronize do
+          consume_message_from_queue! until @batch.full? || @queue.empty?
+        end
+
+        res = @transport.send @api_key, @batch
+        @on_error.call(res.status, res.error) unless res.status == 200
+
+        @lock.synchronize { @batch.clear }
+      end
+    ensure
+      @transport.shutdown
+    end
+
+    # public: Check whether we have outstanding requests.
+    #
+    # TODO: Rename to `requesting?` in future version
+    def is_requesting? # rubocop:disable Naming/PredicateName
+      @lock.synchronize { !@batch.empty? }
+    end
+
+    private
+
+    def consume_message_from_queue!
+      @batch << @queue.pop
+    rescue MessageBatch::JSONGenerationError => e
+      @on_error.call(-1, e.to_s)
+    end
+  end
+end

data/lib/posthog/transport.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'posthog/defaults'
+require 'posthog/utils'
+require 'posthog/response'
+require 'posthog/logging'
+require 'posthog/backoff_policy'
+require 'net/http'
+require 'net/https'
+require 'json'
+
+module PostHog
+  class Transport
+    include PostHog::Defaults::Request
+    include PostHog::Utils
+    include PostHog::Logging
+
+    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
+      @path = options[:path] || PATH
+      @retries = options[:retries] || RETRIES
+      @backoff_policy = options[:backoff_policy] || PostHog::BackoffPolicy.new
+
+      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
+    end
+
+    # Sends a batch of messages to the API
+    #
+    # @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 = JSON.parse(body)['error']
+          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
+    def shutdown
+      @http.finish if @http.started?
+    end
+
+    private
+
+    def should_retry_request?(status_code, body)
+      if status_code >= 500
+        true # Server error
+      elsif status_code == 429 # rubocop:disable Lint/DuplicateBranch
+        true # 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(@backoff_policy.next_interval.to_f / 1000)
+        retry_with_backoff(retries_remaining - 1, &block)
+      else
+        [result, caught_exception]
+      end
+    end
+
+    # Sends a request for the batch, returns [status_code, body]
+    def send_request(api_key, batch)
+      payload = JSON.generate(api_key: api_key, batch: batch)
+
+      request = Net::HTTP::Post.new(@path, @headers)
+
+      if self.class.stub
+        logger.debug "stubbed request to #{@path}: " \
+                     "api key = #{api_key}, batch = #{JSON.generate(batch)}"
+
+        [200, '{}']
+      else
+        @http.start unless @http.started? # Maintain a persistent connection
+        response = @http.request(request, payload)
+        [response.code.to_i, response.body]
+      end
+    end
+
+    class << self
+      attr_writer :stub
+
+      def stub
+        @stub || ENV.fetch('STUB', nil)
+      end
+    end
+  end
+end