mixpanel-ruby 3.2.0 → 3.4.0

data/spec/mixpanel-ruby/flags/local_flags_spec.rb

@@ -486,6 +486,68 @@ describe Mixpanel::Flags::LocalFlagsProvider do
       expect(result).to eq('fallback')
     end
 
+    it 'respects runtime evaluation rule with semver_compare operator when satisfied' do
+      runtime_eval = {
+        'semver_compare' => [{'var' => 'app_version'}, '>=', '1.2.0']
+      }
+      flag = create_test_flag(runtime_evaluation_rule: runtime_eval)
+
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      context = user_context_with_properties({'app_version' => '1.5.0'})
+      result = provider.get_variant_value('test_flag', 'fallback', context)
+
+      expect(result).not_to eq('fallback')
+      expect(['control', 'treatment']).to include(result)
+    end
+
+    it 'respects runtime evaluation rule with semver_compare operator when not satisfied' do
+      runtime_eval = {
+        'semver_compare' => [{'var' => 'app_version'}, '>=', '1.2.0']
+      }
+      flag = create_test_flag(runtime_evaluation_rule: runtime_eval)
+
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      context = user_context_with_properties({'app_version' => '1.0.0'})
+      result = provider.get_variant_value('test_flag', 'fallback', context)
+
+      expect(result).to eq('fallback')
+    end
+
+    it 'respects runtime evaluation rule with datetime_compare operator when satisfied' do
+      runtime_eval = {
+        'datetime_compare' => [{'var' => 'signup'}, '>=', 1_784_160_000_000]
+      }
+      flag = create_test_flag(runtime_evaluation_rule: runtime_eval)
+
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      context = user_context_with_properties({'signup' => '2026-07-17T00:00:00Z'})
+      result = provider.get_variant_value('test_flag', 'fallback', context)
+
+      expect(result).not_to eq('fallback')
+      expect(['control', 'treatment']).to include(result)
+    end
+
+    it 'respects runtime evaluation rule with datetime_compare operator when not satisfied' do
+      runtime_eval = {
+        'datetime_compare' => [{'var' => 'signup'}, '>=', 1_784_160_000_000]
+      }
+      flag = create_test_flag(runtime_evaluation_rule: runtime_eval)
+
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      context = user_context_with_properties({'signup' => '2026-07-15T00:00:00Z'})
+      result = provider.get_variant_value('test_flag', 'fallback', context)
+
+      expect(result).to eq('fallback')
+    end
+
     it 'picks correct variant with hundred percent split' do
       variants = [
         { 'key' => 'A', 'value' => 'variant_a', 'is_control' => false, 'split' => 100.0 },
@@ -749,6 +811,179 @@ describe Mixpanel::Flags::LocalFlagsProvider do
 
       provider.send(:track_exposure_event, 'test_flag', variant, test_context)
     end
+
+    it 'runs the tracker inline by default (no executor configured)' do
+      flag = create_test_flag
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+
+      calling_thread = Thread.current
+      tracker_thread = nil
+      allow(mock_tracker).to receive(:call) { tracker_thread = Thread.current }
+
+      provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+      expect(tracker_thread).to be(calling_thread)
+    end
+
+    it 'dispatches the tracker via :exposure_executor when configured' do
+      executor = Object.new
+      def executor.post(&block)
+        Thread.new(&block)
+      end
+
+      tracker_thread = nil
+      tracker_ran = Queue.new
+      tracker = ->(_distinct_id, _event, _properties) {
+        tracker_thread = Thread.current
+        tracker_ran << :done
+      }
+
+      provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false, exposure_executor: executor },
+        tracker,
+        mock_error_handler
+      )
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+      provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+
+      # Bounded wait — a bare Queue#pop would hang CI forever if the
+      # tracker block raised before pushing :done.
+      Timeout.timeout(2) { tracker_ran.pop }
+      expect(tracker_thread).not_to be(Thread.current)
+    end
+
+    it 'reports non-MixpanelError exceptions from the async tracker to error_handler' do
+      handler_called = Queue.new
+      handler = double('error_handler')
+      allow(handler).to receive(:handle) { |e| handler_called << e }
+
+      executor = Object.new
+      def executor.post(&block)
+        Thread.new(&block)
+      end
+
+      tracker = ->(_distinct_id, _event, _properties) { raise NoMethodError, 'boom' }
+
+      provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false, exposure_executor: executor },
+        tracker,
+        handler
+      )
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+      provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+
+      err = Timeout.timeout(2) { handler_called.pop }
+      expect(err).to be_a(Mixpanel::MixpanelError)
+      expect(err.message).to include('NoMethodError')
+      expect(err.message).to include('boom')
+    end
+
+    # Inline path preserves the pre-executor behavior: non-MixpanelError
+    # from the tracker propagates to the flag evaluator's caller instead
+    # of being silently reported. Only the async path wraps everything,
+    # because on the executor thread propagation would just kill the
+    # background thread with no visibility.
+    it 'lets non-MixpanelError exceptions propagate on the inline path' do
+      tracker = ->(_distinct_id, _event, _properties) { raise NoMethodError, 'boom' }
+
+      inline_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false },
+        tracker,
+        mock_error_handler
+      )
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+
+      expect(mock_error_handler).not_to receive(:handle)
+      expect {
+        inline_provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+      }.to raise_error(NoMethodError, 'boom')
+    end
+
+    # SDK-84: when local eval succeeds via a non-distinct_id Variant Assignment
+    # Key but the context lacks distinct_id, the exposure can't fire. Surface
+    # via error_handler instead of silently returning.
+    it 'reports through error_handler when distinct_id is missing' do
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+
+      expect(mock_tracker).not_to receive(:call)
+      expect(mock_error_handler).to receive(:handle) do |err|
+        expect(err).to be_a(Mixpanel::MixpanelError)
+        expect(err.message).to include('test_flag')
+        expect(err.message).to include('distinct_id')
+      end
+
+      provider.send(
+        :track_exposure_event,
+        'test_flag',
+        variant,
+        { 'device_id' => 'abc-123' }
+      )
+    end
+  end
+
+  describe '#get_variant variant_source / fallback_reason tagging' do
+    let(:fallback) { Mixpanel::Flags::SelectedVariant.new(variant_value: 'fb') }
+
+    it 'tags matched variants as LOCAL with no fallback_reason' do
+      flag = create_test_flag(rollout_percentage: 100.0)
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('test_flag', fallback, test_context)
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::LOCAL)
+      expect(result.fallback_reason).to be_nil
+      expect(result.variant_key).not_to be_nil
+    end
+
+    it 'tags missing flag as FALLBACK / flag_not_found' do
+      stub_flag_definitions([])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('missing', fallback, test_context)
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:flag_not_found)
+      expect(result.fallback_reason.message).to be_nil
+      expect(result.variant_value).to eq('fb')
+    end
+
+    it 'tags missing context as FALLBACK / missing_context_key with the missing attribute' do
+      flag = create_test_flag(context: 'distinct_id')
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('test_flag', fallback, {})
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:missing_context_key)
+      expect(result.fallback_reason.message).to eq('distinct_id')
+    end
+
+    it 'tags no-rollout-match as FALLBACK / no_rollout_match' do
+      flag = create_test_flag(rollout_percentage: 0.0)
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('test_flag', fallback, test_context)
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:no_rollout_match)
+    end
   end
 
   describe 'polling' do
@@ -931,6 +1166,54 @@ describe Mixpanel::Flags::LocalFlagsProvider do
         polling_provider.stop_polling_for_definitions!
       end
     end
+
+    # SDK-78: safe_handle_error previously dispatched only to @error_handler,
+    # whose default Mixpanel::ErrorHandler#handle is a no-op — schema drift
+    # (NoMethodError, JSON::ParserError, etc.) looped forever undetected.
+    # Warn to stderr unconditionally so failures are visible without an
+    # error_handler being configured.
+    it 'warns to stderr when fetch raises and no error_handler is configured' do
+      stub_request(:get, endpoint_url_regex).to_return(status: 500, body: 'server down')
+
+      polling_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false },
+        mock_tracker,
+        nil
+      )
+
+      expect { polling_provider.start_polling_for_definitions! }
+        .to output(/\[Mixpanel\] Failed to fetch flag definitions: Mixpanel::ServerError/).to_stderr
+    end
+
+    # Regression: previously the outer rescue on start_polling_for_definitions!
+    # caught an initial-fetch failure and returned before the @lifecycle_mutex
+    # block ever spawned the poller thread. A single startup blip (transient
+    # 500 / network timeout) left the SDK permanently without a poller until
+    # the caller retried — the whole point of polling.
+    it 'still spawns the polling thread when the initial fetch fails' do
+      stub_request(:get, endpoint_url_regex).to_return(status: 500, body: 'transient')
+
+      polling_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: true, polling_interval_in_seconds: 30 },
+        mock_tracker,
+        nil
+      )
+
+      begin
+        # Warning is expected because the initial fetch fails; capture stderr
+        # so it doesn't pollute test output.
+        expect { polling_provider.start_polling_for_definitions! }
+          .to output(/\[Mixpanel\] Failed to fetch flag definitions/).to_stderr
+
+        polling_thread = polling_provider.instance_variable_get(:@polling_thread)
+        expect(polling_thread).not_to be_nil
+        expect(polling_thread).to be_alive
+      ensure
+        polling_provider.stop_polling_for_definitions!
+      end
+    end
   end
 
   describe 'service account credentials' do

data/spec/mixpanel-ruby/flags/remote_flags_spec.rb

@@ -1,4 +1,5 @@
 require 'json'
+require 'timeout'
 require 'mixpanel-ruby/flags/remote_flags_provider'
 require 'mixpanel-ruby/flags/types'
 require 'mixpanel-ruby/credentials'
@@ -118,6 +119,61 @@ describe Mixpanel::Flags::RemoteFlagsProvider do
       provider.get_variant_value('test_flag', 'control', test_context)
     end
 
+    it 'runs the tracker inline by default (no executor configured)' do
+      response = create_success_response({
+        'test_flag' => {
+          'variant_key' => 'treatment',
+          'variant_value' => 'treatment'
+        }
+      })
+      stub_flags_request(response)
+
+      calling_thread = Thread.current
+      tracker_thread = nil
+      allow(mock_tracker).to receive(:call) { tracker_thread = Thread.current }
+
+      provider.get_variant_value('test_flag', 'control', test_context)
+      expect(tracker_thread).to be(calling_thread)
+    end
+
+    it 'dispatches the tracker via the configured exposure_executor off the calling thread' do
+      response = create_success_response({
+        'test_flag' => {
+          'variant_key' => 'treatment',
+          'variant_value' => 'treatment'
+        }
+      })
+      stub_flags_request(response)
+
+      calling_thread = Thread.current
+      tracker_thread = nil
+      tracker_ran = Queue.new
+      tracker = ->(_distinct_id, _event, _properties) {
+        tracker_thread = Thread.current
+        tracker_ran << :done
+      }
+
+      # Minimal duck-typed executor: spawn a thread per call.
+      executor = Object.new
+      def executor.post(&block)
+        Thread.new(&block)
+      end
+
+      provider = Mixpanel::Flags::RemoteFlagsProvider.new(
+        test_token,
+        { exposure_executor: executor },
+        tracker,
+        mock_error_handler
+      )
+
+      provider.get_variant_value('test_flag', 'control', test_context)
+
+      # Bounded wait — a bare Queue#pop would hang CI forever if the
+      # tracker block raised before pushing :done.
+      Timeout.timeout(2) { tracker_ran.pop }
+      expect(tracker_thread).not_to be(calling_thread)
+    end
+
     it 'does not track exposure event when report_exposure is false' do
       response = create_success_response({
         'test_flag' => {
@@ -259,6 +315,18 @@ describe Mixpanel::Flags::RemoteFlagsProvider do
 
       provider.get_variant('any-flag', fallback_variant, test_context)
     end
+
+    it 'tags the fallback as BACKEND_ERROR with the response body on HTTP error (SDK-83)' do
+      stub_request(:get, %r{https://api\.mixpanel\.com/flags})
+        .to_return(status: 400, body: 'distinct_id must be provided in evalContext as a string')
+
+      fallback_variant = Mixpanel::Flags::SelectedVariant.new(variant_value: 'fb')
+      result = provider.get_variant('any-flag', fallback_variant, test_context, report_exposure: false)
+
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:backend_error)
+      expect(result.fallback_reason.message).to include('distinct_id must be provided')
+    end
   end
 
   describe '#is_enabled' do

data/spec/mixpanel-ruby/flags/types_spec.rb

@@ -0,0 +1,55 @@
+require 'json'
+require 'mixpanel-ruby/flags/types'
+
+describe Mixpanel::Flags::SelectedVariant do
+  describe '#to_h' do
+    it 'returns a plain hash for a matched variant' do
+      variant = described_class.new(
+        variant_key: 'treatment',
+        variant_value: 'v1',
+        experiment_id: 'exp-1',
+        is_experiment_active: true,
+        variant_source: Mixpanel::Flags::VariantSource::LOCAL
+      )
+
+      expect(variant.to_h).to eq(
+        variant_key: 'treatment',
+        variant_value: 'v1',
+        experiment_id: 'exp-1',
+        is_experiment_active: true,
+        variant_source: 'local'
+      )
+    end
+
+    # SDK-125: previously to_h returned the raw FallbackReason object under
+    # :fallback_reason, so downstream serializers (e.g. .to_json,
+    # structured logging) got an object representation instead of the
+    # {kind:, message:} hash FallbackReason itself defines.
+    it 'recurses into FallbackReason so the result is fully hash-y' do
+      variant = described_class.new(
+        variant_value: 'fallback-value',
+        variant_source: Mixpanel::Flags::VariantSource::FALLBACK,
+        fallback_reason: Mixpanel::Flags::FallbackReason.backend_error('boom')
+      )
+
+      expect(variant.to_h[:fallback_reason]).to eq(kind: :backend_error, message: 'boom')
+    end
+
+    it 'round-trips through JSON without leaking a FallbackReason object' do
+      variant = described_class.new(
+        variant_value: 'fallback-value',
+        variant_source: Mixpanel::Flags::VariantSource::FALLBACK,
+        fallback_reason: Mixpanel::Flags::FallbackReason.missing_context_key('distinct_id')
+      )
+
+      parsed = JSON.parse(variant.to_h.to_json, symbolize_names: true)
+
+      expect(parsed[:fallback_reason]).to eq(kind: 'missing_context_key', message: 'distinct_id')
+    end
+
+    it 'compacts fallback_reason when absent' do
+      variant = described_class.new(variant_value: 'x', variant_source: 'local')
+      expect(variant.to_h).not_to have_key(:fallback_reason)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixpanel-ruby
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Mixpanel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mutex_m
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -194,6 +194,7 @@ files:
 - lib/mixpanel-ruby/credentials.rb
 - lib/mixpanel-ruby/error.rb
 - lib/mixpanel-ruby/events.rb
+- lib/mixpanel-ruby/flags/custom_operators.rb
 - lib/mixpanel-ruby/flags/flags_provider.rb
 - lib/mixpanel-ruby/flags/local_flags_provider.rb
 - lib/mixpanel-ruby/flags/remote_flags_provider.rb
@@ -214,13 +215,17 @@ files:
 - openfeature-provider/mixpanel-ruby-openfeature.gemspec
 - openfeature-provider/spec/mixpanel_openfeature_provider_spec.rb
 - openfeature-provider/spec/spec_helper.rb
+- spec/fixtures/datetime_compare_tests.json
+- spec/fixtures/semver_compare_tests.json
 - spec/mixpanel-ruby/consumer_spec.rb
 - spec/mixpanel-ruby/credentials_security_spec.rb
 - spec/mixpanel-ruby/credentials_spec.rb
 - spec/mixpanel-ruby/error_spec.rb
 - spec/mixpanel-ruby/events_spec.rb
+- spec/mixpanel-ruby/flags/custom_operators_spec.rb
 - spec/mixpanel-ruby/flags/local_flags_spec.rb
 - spec/mixpanel-ruby/flags/remote_flags_spec.rb
+- spec/mixpanel-ruby/flags/types_spec.rb
 - spec/mixpanel-ruby/flags/utils_spec.rb
 - spec/mixpanel-ruby/groups_spec.rb
 - spec/mixpanel-ruby/people_spec.rb