mixpanel-ruby 2.3.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a4bc0206903c9c7d7e61253d7cfe248e17f698a754dac067e3d6997ee44688a
-  data.tar.gz: eda4910784b73583c7ff29fcbeaae86b1259e407d8cddf5c5c9ccb7ad9004661
+  metadata.gz: 99f6ea359c1b7a0f4248035f2ebe9a13380ee647b20722f73f49f45b3bb62ea3
+  data.tar.gz: c1dc8bf0e37d90a397654b263059458291eff144987b87bc3a9dcc153649c42e
 SHA512:
-  metadata.gz: ba267b81907f663ef400b694973569c2e2e00c323e8e199bea82516d3552c73f2ffcc6c864c0fca2123f53a3e246218e60c64e58b51aab5ac96792dae8f76a13
-  data.tar.gz: 541c0b8b4da498f37a749d76542fad417c776c83f4d583c8ae5bbbfbba9979103cfb634bb4a3d8ae6748b6b302ca546524edc80258423eb2e862d279328d07f1
+  metadata.gz: cee44f99c3d4000ee9eb64a0353abcee02bec2a422d0a27c9cda160c8bb50db3f6abe72c550730633c719a51eb06f92dbba5e38cc17f7266a82bf8561488005e
+  data.tar.gz: db60ba774c9e32e2bb4199d46a3c192a40d35d3aaef84fdb87c0e29a7a66f76b4f4dbd0c6e2f28d5d7145844fadb91b9ccefb4bd82d2d9e2f287153182fcf176

data/.github/workflows/ruby.yml

@@ -0,0 +1,37 @@
+name: Ruby
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request: {}
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version:
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@d697be2f83c6234b20877c3b5eac7a7f342f0d0c # v1.269.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        slug: mixpanel/mixpanel-ruby

data/Readme.rdoc

@@ -1,5 +1,3 @@
-{<img src="https://travis-ci.org/mixpanel/mixpanel-ruby.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/mixpanel/mixpanel-ruby]
-
 = mixpanel-ruby: The official Mixpanel Ruby library
 
 mixpanel-ruby is a library for tracking events and sending \Mixpanel profile
@@ -49,6 +47,14 @@ In particular, for Rails apps, the following projects are currently actively mai
 
 == Changes
 
+== 2.3.1
+* Convert timestamps to milliseconds and update Ruby compatibility
+
+== 2.3.0
+* Clear submitted slices during BufferedConsumer#flush
+* Groups analytics support
+* use millisecond precision for time properties
+
 == 2.2.2
 * Add Group Analytics support with Mixpanel::Groups
 

data/demo/flags/local_flags.rb

@@ -0,0 +1,25 @@
+require 'mixpanel-ruby'
+
+# Configuration
+PROJECT_TOKEN = ""
+FLAG_KEY = "sample-flag"
+FLAG_FALLBACK_VARIANT = "control"
+USER_CONTEXT = { "distinct_id" => "ruby-demo-user" }
+API_HOST = "api.mixpanel.com"
+SHOULD_POLL_CONTINUOUSLY = true
+POLLING_INTERVAL_SECONDS = 15
+
+local_config = {
+  api_host: API_HOST,
+  enable_polling: SHOULD_POLL_CONTINUOUSLY,
+  polling_interval_in_seconds: POLLING_INTERVAL_SECONDS
+}
+
+tracker = Mixpanel::Tracker.new(PROJECT_TOKEN, local_flags_config: local_config)
+
+tracker.local_flags.start_polling_for_definitions!
+
+variant_value = tracker.local_flags.get_variant_value(FLAG_KEY, FLAG_FALLBACK_VARIANT, USER_CONTEXT)
+puts "Variant value: #{variant_value}"
+
+tracker.local_flags.stop_polling_for_definitions!

data/demo/flags/remote_flags.rb

@@ -0,0 +1,18 @@
+require 'mixpanel-ruby'
+
+# Configuration
+PROJECT_TOKEN = ""
+FLAG_KEY = "sample-flag"
+FLAG_FALLBACK_VARIANT = "control"
+USER_CONTEXT = { "distinct_id" => "ruby-demo-user" }
+API_HOST = "api.mixpanel.com"
+
+remote_config = {
+  api_host: API_HOST
+}
+
+tracker = Mixpanel::Tracker.new(PROJECT_TOKEN, remote_flags_config: remote_config)
+
+variant_value = tracker.remote_flags.get_variant_value(FLAG_KEY, FLAG_FALLBACK_VARIANT, USER_CONTEXT)
+puts "Variant value: #{variant_value}"
+

data/lib/mixpanel-ruby/events.rb

@@ -55,7 +55,7 @@ module Mixpanel
       properties = {
         'distinct_id' => distinct_id,
         'token' => @token,
-        'time' => Time.now.to_f,
+        'time' => (Time.now.to_f * 1000).to_i,
         'mp_lib' => 'ruby',
         '$lib_version' => Mixpanel::VERSION,
       }.merge(properties)
@@ -103,7 +103,7 @@ module Mixpanel
       properties = {
         'distinct_id' => distinct_id,
         'token' => @token,
-        'time' => Time.now.to_f,
+        'time' => (Time.now.to_f * 1000).to_i,
         'mp_lib' => 'ruby',
         '$lib_version' => Mixpanel::VERSION,
       }.merge(properties)

data/lib/mixpanel-ruby/flags/flags_provider.rb

@@ -0,0 +1,111 @@
+require 'net/https'
+require 'json'
+require 'uri'
+require 'mixpanel-ruby/version'
+require 'mixpanel-ruby/error'
+require 'mixpanel-ruby/flags/utils'
+require 'mixpanel-ruby/flags/types'
+
+module Mixpanel
+  module Flags
+
+    # Base class for feature flags providers
+    # Provides common HTTP handling and exposure event tracking
+    class FlagsProvider
+      # @param provider_config [Hash] Configuration with :token, :api_host, :request_timeout_in_seconds
+      # @param endpoint [String] API endpoint path (e.g., '/flags' or '/flags/definitions')
+      # @param tracker_callback [Proc] Function used to track events (bound tracker.track method)
+      # @param evaluation_mode [String] The feature flag evaluation mode. This is either 'local' or 'remote'
+      # @param error_handler [Mixpanel::ErrorHandler] Error handler instance
+      def initialize(provider_config, endpoint, tracker_callback, evaluation_mode, error_handler)
+        @provider_config = provider_config
+        @endpoint = endpoint
+        @tracker_callback = tracker_callback
+        @evaluation_mode = evaluation_mode
+        @error_handler = error_handler
+      end
+
+      # Make HTTP request to flags API endpoint
+      # @param additional_params [Hash, nil] Additional query parameters
+      # @return [Hash] Parsed JSON response
+      # @raise [Mixpanel::ConnectionError] on network errors
+      # @raise [Mixpanel::ServerError] on HTTP errors
+      def call_flags_endpoint(additional_params = nil)
+        common_params = Utils.prepare_common_query_params(
+          @provider_config[:token],
+          Mixpanel::VERSION
+        )
+
+        params = common_params.merge(additional_params || {})
+        query_string = URI.encode_www_form(params)
+
+        uri = URI::HTTPS.build(
+          host: @provider_config[:api_host],
+          path: @endpoint,
+          query: query_string
+        )
+
+        http = Net::HTTP.new(uri.host, uri.port)
+
+        http.use_ssl = true
+        http.open_timeout = @provider_config[:request_timeout_in_seconds]
+        http.read_timeout = @provider_config[:request_timeout_in_seconds]
+
+        request = Net::HTTP::Get.new(uri.request_uri)
+
+        request.basic_auth(@provider_config[:token], '')
+
+        request['Content-Type'] = 'application/json'
+        request['traceparent'] = Utils.generate_traceparent()
+
+        begin
+          response = http.request(request)
+
+          unless response.code.to_i == 200
+            raise ServerError.new("HTTP #{response.code}: #{response.body}")
+          end
+
+          JSON.parse(response.body)
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          raise ConnectionError.new("Request timeout: #{e.message}")
+        rescue JSON::ParserError => e
+          raise ServerError.new("Invalid JSON response: #{e.message}")
+        rescue StandardError => e
+          raise ConnectionError.new("Network error: #{e.message}")
+        end
+      end
+
+      # Track exposure event to Mixpanel
+      # @param flag_key [String] Feature flag key
+      # @param selected_variant [SelectedVariant] The selected variant
+      # @param context [Hash] User context (must include 'distinct_id')
+      # @param latency_ms [Integer, nil] Optional latency in milliseconds
+      def track_exposure_event(flag_key, selected_variant, context, latency_ms = nil)
+        distinct_id = context['distinct_id'] || context[:distinct_id]
+
+        unless distinct_id
+          return
+        end
+
+        properties = {
+          'distinct_id' => distinct_id,
+          'Experiment name' => flag_key,
+          'Variant name' => selected_variant.variant_key,
+          '$experiment_type' => 'feature_flag',
+          'Flag evaluation mode' => @evaluation_mode
+        }
+
+        properties['Variant fetch latency (ms)'] = latency_ms if latency_ms
+        properties['$experiment_id'] = selected_variant.experiment_id if selected_variant.experiment_id
+        properties['$is_experiment_active'] = selected_variant.is_experiment_active unless selected_variant.is_experiment_active.nil?
+        properties['$is_qa_tester'] = selected_variant.is_qa_tester unless selected_variant.is_qa_tester.nil?
+
+        begin
+          @tracker_callback.call(distinct_id, Utils::EXPOSURE_EVENT, properties)
+        rescue MixpanelError => e
+          @error_handler.handle(e)
+        end
+      end
+    end
+  end
+end

data/lib/mixpanel-ruby/flags/local_flags_provider.rb

@@ -0,0 +1,303 @@
+require 'thread'
+require 'json_logic'
+require 'mixpanel-ruby/flags/flags_provider'
+
+module Mixpanel
+  module Flags
+    # Local feature flags provider
+    # Evaluates flags client-side with cached flag definitions
+    class LocalFlagsProvider < FlagsProvider
+      DEFAULT_CONFIG = {
+        api_host: 'api.mixpanel.com',
+        request_timeout_in_seconds: 10,
+        enable_polling: true,
+        polling_interval_in_seconds: 60
+      }.freeze
+
+      # @param token [String] Mixpanel project token
+      # @param config [Hash] Local flags configuration
+      # @param tracker_callback [Proc] Callback to track events
+      # @param error_handler [Mixpanel::ErrorHandler] Error handler
+      def initialize(token, config, tracker_callback, error_handler)
+        @config = DEFAULT_CONFIG.merge(config || {})
+
+        provider_config = {
+          token: token,
+          api_host: @config[:api_host],
+          request_timeout_in_seconds: @config[:request_timeout_in_seconds]
+        }
+
+        super(provider_config, '/flags/definitions', tracker_callback, 'local', error_handler)
+
+        @flag_definitions = {}
+        @polling_thread = nil
+        @stop_polling = false
+      end
+
+      # Start polling for flag definitions
+      # Fetches immediately, then at regular intervals if polling enabled
+      def start_polling_for_definitions!
+        fetch_flag_definitions
+
+        if @config[:enable_polling] && !@polling_thread
+          @stop_polling = false
+          @polling_thread = Thread.new do
+            loop do
+              sleep @config[:polling_interval_in_seconds]
+              break if @stop_polling
+
+              begin
+                fetch_flag_definitions
+              rescue StandardError => e
+                @error_handler.handle(e) if @error_handler
+              end
+            end
+          end
+        end
+      rescue StandardError => e
+        @error_handler.handle(e) if @error_handler
+      end
+
+      def stop_polling_for_definitions!
+        @stop_polling = true
+        @polling_thread&.join
+        @polling_thread = nil
+      end
+
+      # Check if flag is enabled (for boolean flags)
+      # @param flag_key [String] Feature flag key
+      # @param context [Hash] Evaluation context (must include 'distinct_id')
+      # @return [Boolean]
+      def is_enabled?(flag_key, context)
+        value = get_variant_value(flag_key, false, context)
+        value == true
+      end
+
+      # Get variant value for a flag
+      # @param flag_key [String] Feature flag key
+      # @param fallback_value [Object] Fallback value if not in rollout
+      # @param context [Hash] Evaluation context
+      # @param report_exposure [Boolean] Whether to track exposure event
+      # @return [Object] The variant value
+      def get_variant_value(flag_key, fallback_value, context, report_exposure: true)
+        result = get_variant(
+          flag_key,
+          SelectedVariant.new(variant_value: fallback_value),
+          context,
+          report_exposure: report_exposure
+        )
+        result.variant_value
+      end
+
+      # Get complete variant information
+      # @param flag_key [String] Feature flag key
+      # @param fallback_variant [SelectedVariant] Fallback variant
+      # @param context [Hash] Evaluation context
+      # @param report_exposure [Boolean] Whether to track exposure event
+      # @return [SelectedVariant]
+      def get_variant(flag_key, fallback_variant, context, report_exposure: true)
+        flag = @flag_definitions[flag_key]
+
+        return fallback_variant unless flag
+
+        context_key = flag['context']
+        unless context.key?(context_key) || context.key?(context_key.to_sym)
+          return fallback_variant
+        end
+
+        context_value = context[context_key] || context[context_key.to_sym]
+
+        selected_variant = nil
+
+        test_variant = get_variant_override_for_test_user(flag, context)
+        if test_variant
+          selected_variant = test_variant
+        else
+          rollout = get_assigned_rollout(flag, context_value, context)
+          if rollout
+            selected_variant = get_assigned_variant(flag, context_value, flag_key, rollout)
+          end
+        end
+
+        if selected_variant
+          track_exposure_event(flag_key, selected_variant, context) if report_exposure
+          return selected_variant
+        end
+
+        fallback_variant
+      end
+
+      # Get all variants for user context
+      # Exposure events NOT tracked automatically
+      # @param context [Hash] Evaluation context
+      # @return [Hash] Map of flag_key => SelectedVariant
+      def get_all_variants(context)
+        variants = {}
+
+        @flag_definitions.each_key do |flag_key|
+          variant = get_variant(flag_key, nil, context, report_exposure: false)
+          variants[flag_key] = variant if variant
+        end
+
+        variants
+      end
+
+      private
+
+      def fetch_flag_definitions
+        response = call_flags_endpoint
+
+        new_definitions = {}
+        (response['flags'] || []).each do |flag_data|
+          new_definitions[flag_data['key']] = flag_data
+        end
+
+        @flag_definitions = new_definitions
+
+        response
+      end
+
+      def get_variant_override_for_test_user(flag, context)
+        test_users = flag.dig('ruleset', 'test', 'users')
+        return nil unless test_users
+
+        distinct_id = context['distinct_id'] || context[:distinct_id]
+        return nil unless distinct_id
+
+        variant_key = test_users[distinct_id.to_s]
+        return nil unless variant_key
+
+        variant = get_matching_variant(variant_key, flag)
+        if variant
+          variant.is_qa_tester = true
+        end
+        variant
+      end
+
+      def get_matching_variant(variant_key, flag)
+        return nil unless flag['ruleset'] && flag['ruleset']['variants']
+
+        flag['ruleset']['variants'].each do |v|
+          if variant_key.downcase == v['key'].downcase
+            return SelectedVariant.new(
+              variant_key: v['key'],
+              variant_value: v['value'],
+              experiment_id: flag['experiment_id'],
+              is_experiment_active: flag['is_experiment_active']
+            )
+          end
+        end
+        nil
+      end
+
+      def get_assigned_rollout(flag, context_value, context)
+        return nil unless flag['ruleset'] && flag['ruleset']['rollout']
+
+        flag['ruleset']['rollout'].each_with_index do |rollout, index|
+          salt = if flag['hash_salt']
+                   "#{flag['key']}#{flag['hash_salt']}#{index}"
+                 else
+                   "#{flag['key']}rollout"
+                 end
+
+          rollout_hash = Utils.normalized_hash(context_value.to_s, salt)
+
+          if rollout_hash < rollout['rollout_percentage'] &&
+             is_runtime_evaluation_satisfied?(rollout, context)
+            return rollout
+          end
+        end
+
+        nil
+      end
+
+      def get_assigned_variant(flag, context_value, flag_key, rollout)
+        if rollout['variant_override']
+          variant = get_matching_variant(rollout['variant_override']['key'], flag)
+          if variant
+            variant.is_qa_tester = false
+            return variant
+          end
+        end
+
+        stored_salt = flag['hash_salt'] || ''
+        salt = "#{flag_key}#{stored_salt}variant"
+        variant_hash = Utils.normalized_hash(context_value.to_s, salt)
+
+        variants = flag['ruleset']['variants'].map { |v| v.dup }
+        if rollout['variant_splits']
+          variants.each do |v|
+            v['split'] = rollout['variant_splits'][v['key']] if rollout['variant_splits'].key?(v['key'])
+          end
+        end
+
+        selected = variants.first
+        cumulative = 0.0
+        variants.each do |v|
+          selected = v
+          cumulative += (v['split'] || 0.0)
+          break if variant_hash < cumulative
+        end
+
+        SelectedVariant.new(
+          variant_key: selected['key'],
+          variant_value: selected['value'],
+          experiment_id: flag['experiment_id'],
+          is_experiment_active: flag['is_experiment_active'],
+          is_qa_tester: false
+        )
+      end
+
+      def lowercase_keys_and_values(val)
+        case val
+        when String
+          val.downcase
+        when Array
+          val.map { |item| lowercase_keys_and_values(item) }
+        when Hash
+          val.transform_keys { |k| k.is_a?(String) ? k.downcase : k }
+             .transform_values { |v| lowercase_keys_and_values(v) }
+        else
+          val
+        end
+      end
+
+      def lowercase_only_leaf_nodes(val)
+        case val
+        when String
+          val.downcase
+        when Array
+          val.map { |item| lowercase_only_leaf_nodes(item) }
+        when Hash
+          val.transform_values { |v| lowercase_only_leaf_nodes(v) }
+        else
+          val
+        end
+      end
+
+      def get_runtime_parameters(context)
+        custom_props = context['custom_properties'] || context[:custom_properties]
+        return nil unless custom_props && custom_props.is_a?(Hash)
+
+        lowercase_keys_and_values(custom_props)
+      end
+
+      def is_runtime_evaluation_satisfied?(rollout, context)
+        runtime_rule = rollout['runtime_evaluation_rule']
+        return true unless runtime_rule
+
+        parameters = get_runtime_parameters(context)
+        return false unless parameters
+
+        begin
+          rule = lowercase_only_leaf_nodes(runtime_rule)
+          result = JsonLogic.apply(rule, parameters)
+          !!result
+        rescue StandardError => e
+          @error_handler.handle(e) if @error_handler
+          false
+        end
+      end
+    end
+  end
+end

data/lib/mixpanel-ruby/flags/remote_flags_provider.rb

@@ -0,0 +1,134 @@
+require 'mixpanel-ruby/flags/flags_provider'
+
+module Mixpanel
+  module Flags
+    # Remote feature flags provider
+    # Evaluates flags on the server-side via HTTP API calls
+    class RemoteFlagsProvider < FlagsProvider
+      DEFAULT_CONFIG = {
+        api_host: 'api.mixpanel.com',
+        request_timeout_in_seconds: 10
+      }.freeze
+
+      # @param token [String] Mixpanel project token
+      # @param config [Hash] Remote flags configuration
+      # @param tracker_callback [Proc] Callback to track events
+      # @param error_handler [Mixpanel::ErrorHandler] Error handler
+      def initialize(token, config, tracker_callback, error_handler)
+        merged_config = DEFAULT_CONFIG.merge(config || {})
+
+        provider_config = {
+          token: token,
+          api_host: merged_config[:api_host],
+          request_timeout_in_seconds: merged_config[:request_timeout_in_seconds]
+        }
+
+        super(provider_config, '/flags', tracker_callback, 'remote', error_handler)
+      end
+
+      # Get variant value for a flag
+      # @param flag_key [String] Feature flag key
+      # @param fallback_value [Object] Fallback value
+      # @param context [Hash] Evaluation context
+      # @param report_exposure [Boolean] Whether to track exposure
+      # @return [Object] Variant value
+      def get_variant_value(flag_key, fallback_value, context, report_exposure: true)
+        selected_variant = get_variant(
+          flag_key,
+          SelectedVariant.new(variant_value: fallback_value),
+          context,
+          report_exposure: report_exposure
+        )
+        selected_variant.variant_value
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        fallback_value
+      end
+
+      # Get complete variant information
+      # @param flag_key [String] Feature flag key
+      # @param fallback_variant [SelectedVariant] Fallback variant
+      # @param context [Hash] Evaluation context
+      # @param report_exposure [Boolean] Whether to track exposure
+      # @return [SelectedVariant]
+      def get_variant(flag_key, fallback_variant, context, report_exposure: true)
+        start_time = Time.now
+        response = fetch_flags(context, flag_key)
+        latency_ms = ((Time.now - start_time) * 1000).to_i
+
+        flags = response['flags'] || {}
+        selected_variant_data = flags[flag_key]
+
+        return fallback_variant unless selected_variant_data
+
+        selected_variant = SelectedVariant.new(
+          variant_key: selected_variant_data['variant_key'],
+          variant_value: selected_variant_data['variant_value'],
+          experiment_id: selected_variant_data['experiment_id'],
+          is_experiment_active: selected_variant_data['is_experiment_active']
+        )
+
+        track_exposure_event(flag_key, selected_variant, context, latency_ms) if report_exposure
+
+        return selected_variant
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        return fallback_variant
+      end
+
+      # Check if flag is enabled (for boolean flags)
+      # This method is intended only for flags defined as Mixpanel Feature Gates (boolean flags)
+      # This checks that the variant value of a selected variant is concretely the boolean 'true'
+      # It does not coerce other truthy values.
+      # @param flag_key [String] Feature flag key
+      # @param context [Hash] Evaluation context
+      # @return [Boolean]
+      def is_enabled?(flag_key, context)
+        value = get_variant_value(flag_key, false, context)
+        value == true
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        false
+      end
+
+      # Get all variants for user context
+      # Exposure events NOT tracked automatically
+      # @param context [Hash] Evaluation context
+      # @return [Hash, nil] Map of flag_key => SelectedVariant, or nil on error
+      def get_all_variants(context)
+        response = fetch_flags(context)
+
+        variants = {}
+        (response['flags'] || {}).each do |flag_key, variant_data|
+          variants[flag_key] = SelectedVariant.new(
+            variant_key: variant_data['variant_key'],
+            variant_value: variant_data['variant_value'],
+            experiment_id: variant_data['experiment_id'],
+            is_experiment_active: variant_data['is_experiment_active']
+          )
+        end
+
+        variants
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        nil
+      end
+
+      private
+
+      # Fetch flags from remote API
+      # @param context [Hash] Evaluation context
+      # @param flag_key [String, nil] Optional specific flag key
+      # @return [Hash] API response
+      def fetch_flags(context, flag_key = nil)
+        additional_params = {
+          'context' => JSON.generate(context)
+        }
+
+        additional_params['flag_key'] = flag_key if flag_key
+
+        call_flags_endpoint(additional_params)
+      end
+    end
+  end
+end