mixpanel-ruby 3.1.0 → 3.3.0

data/Readme.rdoc

@@ -1,5 +1,7 @@
 = mixpanel-ruby: The official Mixpanel Ruby library
 
+##### _July 24, 2026_ - [v3.3.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/v3.3.0)
+
 mixpanel-ruby is a library for tracking events and sending \Mixpanel profile
 updates to \Mixpanel from your ruby applications.
 
@@ -27,6 +29,69 @@ The primary class you will use to track events is Mixpanel::Tracker. An instance
 Mixpanel::Tracker is enough to send events directly to \Mixpanel, and get you integrated
 right away.
 
+== Service Account Authentication
+
+Service accounts provide secure server-to-server authentication and are recommended over
+API keys for import operations and feature flags.
+
+=== Import with Service Account (Recommended)
+
+    require 'mixpanel-ruby'
+
+    # Create service account credentials
+    credentials = Mixpanel::ServiceAccountCredentials.new(
+        'your-service-account-username',
+        'your-service-account-secret',
+        'your-project-id'
+    )
+
+    # Pass credentials to tracker constructor
+    # Credentials are stored securely and never serialized to JSON
+    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+
+    # Import historical events using import_events (recommended)
+    tracker.import_events('User1', 'Past Event', {
+        'time' => 1369353600,
+        'Source' => 'Import'
+    })
+
+    # Alternative: use import() with nil as first parameter
+    tracker.import(nil, 'User1', 'Past Event', {
+        'time' => 1369353600,
+        'Source' => 'Import'
+    })
+
+=== Import with API Key (Legacy)
+
+    # Legacy approach with API key string
+    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
+    tracker.import("API_KEY", 'User1', 'Past Event', {
+        'time' => 1369353600,
+        'Source' => 'Import'
+    })
+
+=== Feature Flags with Service Account
+
+    require 'mixpanel-ruby'
+
+    credentials = Mixpanel::ServiceAccountCredentials.new(
+        'your-service-account-username',
+        'your-service-account-secret',
+        'your-project-id'
+    )
+
+    # Pass credentials directly to the tracker
+    tracker = Mixpanel::Tracker.new(
+        YOUR_MIXPANEL_TOKEN,
+        nil,
+        credentials: credentials,
+        local_flags_config: {},
+        remote_flags_config: {}
+    )
+
+    # Use feature flags
+    is_enabled = tracker.remote_flags.is_enabled?('my-flag', { 'distinct_id' => 'User1' })
+
 == Additional Information
 
 For more information please visit:

data/lib/mixpanel-ruby/consumer.rb

@@ -40,6 +40,11 @@ module Mixpanel
   #        @kestrel.set(ANALYTICS_QUEUE, [type, message].to_json)
   #    end
   #
+  # IMPORTANT SECURITY NOTE: Always pass credentials to the Consumer or Tracker
+  # constructor (credentials: ...). Credentials are stored as instance variables
+  # and used only for HTTP Basic Auth headers - they never appear in message JSON,
+  # preventing accidental credential leakage in logs or queue storage.
+  #
   # You can also instantiate the library consumers yourself, and use
   # them wherever you would like. For example, the working that
   # consumes the above queue might work like this:
@@ -58,14 +63,19 @@ module Mixpanel
     # they will be used instead of the default Mixpanel endpoints.
     # This can be useful for proxying, debugging, or if you prefer
     # not to use SSL for your events.
+    #
+    # @param credentials [ServiceAccountCredentials, nil] Service account credentials for authentication.
+    #   Credentials are only used for the /import endpoint and feature flags.
     def initialize(events_endpoint=nil,
                    update_endpoint=nil,
                    groups_endpoint=nil,
-                   import_endpoint=nil)
+                   import_endpoint=nil,
+                   credentials: nil)
       @events_endpoint = events_endpoint || 'https://api.mixpanel.com/track'
       @update_endpoint = update_endpoint || 'https://api.mixpanel.com/engage'
       @groups_endpoint = groups_endpoint || 'https://api.mixpanel.com/groups'
       @import_endpoint = import_endpoint || 'https://api.mixpanel.com/import'
+      @credentials = credentials
     end
 
     # Send the given string message to Mixpanel. Type should be
@@ -85,13 +95,26 @@ module Mixpanel
 
       decoded_message = JSON.load(message)
       api_key = decoded_message["api_key"]
+
       data = Base64.encode64(decoded_message["data"].to_json).gsub("\n", '')
 
       form_data = {"data" => data, "verbose" => 1}
-      form_data.merge!("api_key" => api_key) if api_key
+
+      # Only add api_key to form data if using legacy API key (not service account credentials)
+      # Service account credentials use HTTP Basic Auth instead
+      if api_key && !@credentials
+        form_data.merge!("api_key" => api_key)
+      end
 
       begin
-        response_code, response_body = request(endpoint, form_data)
+        # Use keyword arguments for credentials to maintain backward compatibility
+        # with custom Consumer subclasses that override request(endpoint, form_data)
+        response_code, response_body =
+          if @credentials && type == :import
+            request(endpoint, form_data, credentials: @credentials, type: type)
+          else
+            request(endpoint, form_data)
+          end
       rescue => e
         raise ConnectionError.new("Could not connect to Mixpanel, with error \"#{e.message}\".")
       end
@@ -123,11 +146,32 @@ module Mixpanel
     #
     # as the result of the response. Response code should be nil if
     # the request never receives a response for some reason.
-    def request(endpoint, form_data)
+    #
+    # For service account authentication, pass credentials (ServiceAccountCredentials object)
+    # and type (:import) as keyword arguments.
+    # The positional parameters are preserved for backward compatibility with custom Consumer subclasses.
+    def request(endpoint, form_data, credentials: nil, type: nil)
       uri = URI(endpoint)
+
+      # Add project_id as query parameter for import endpoint with service account credentials
+      if credentials && type == :import
+        unless credentials.is_a?(ServiceAccountCredentials)
+          raise ArgumentError, "credentials must be ServiceAccountCredentials, got #{credentials.class}"
+        end
+
+        query_params = URI.decode_www_form(uri.query || '').to_h
+        query_params['project_id'] = credentials.project_id
+        uri.query = URI.encode_www_form(query_params)
+      end
+
       request = Net::HTTP::Post.new(uri.request_uri)
       request.set_form_data(form_data)
 
+      # Use Basic Auth with service account credentials for import endpoint
+      if credentials && type == :import
+        request.basic_auth(credentials.username, credentials.secret)
+      end
+
       client = Net::HTTP.new(uri.host, uri.port)
       client.use_ssl = true
       client.open_timeout = 10
@@ -182,17 +226,21 @@ module Mixpanel
     # to the Mixpanel::Tracker constructor. If a block is passed to
     # the constructor, the *_endpoint constructor arguments are
     # ignored.
-    def initialize(events_endpoint=nil, update_endpoint=nil, import_endpoint=nil, max_buffer_length=MAX_LENGTH, &block)
+    #
+    # @param credentials [ServiceAccountCredentials, nil] Service account credentials for authentication.
+    #   Credentials are only used for the /import endpoint and feature flags.
+    def initialize(events_endpoint=nil, update_endpoint=nil, import_endpoint=nil, max_buffer_length=MAX_LENGTH, credentials: nil, &block)
       @max_length = [max_buffer_length, MAX_LENGTH].min
       @buffers = {
         :event => [],
         :profile_update => [],
       }
+      @credentials = credentials
 
       if block
         @sink = block
       else
-        consumer = Consumer.new(events_endpoint, update_endpoint, import_endpoint)
+        consumer = Consumer.new(events_endpoint, update_endpoint, nil, import_endpoint, credentials: credentials)
         @sink = consumer.method(:send!)
       end
     end

data/lib/mixpanel-ruby/credentials.rb

@@ -0,0 +1,26 @@
+module Mixpanel
+  # Service account credentials for server-to-server authentication
+  # This is the recommended authentication method over API keys
+  class ServiceAccountCredentials
+    attr_reader :username, :secret, :project_id
+
+    # Create service account credentials
+    # @param username [String] Service account username
+    # @param secret [String] Service account secret
+    # @param project_id [String, Integer] Mixpanel project ID (accepts string or integer)
+    def initialize(username, secret, project_id)
+      raise ArgumentError, 'username is required' if username.nil? || username.empty?
+      raise ArgumentError, 'secret is required' if secret.nil? || secret.empty?
+      raise ArgumentError, 'project_id is required' if project_id.nil?
+
+      # Convert project_id to string if it's an integer (Mixpanel dashboard shows numeric IDs)
+      project_id = project_id.to_s if project_id.is_a?(Integer)
+      raise ArgumentError, 'project_id is required' if project_id.empty?
+
+      @username = username
+      @secret = secret
+      @project_id = project_id
+    end
+
+  end
+end

data/lib/mixpanel-ruby/events.rb

@@ -22,14 +22,19 @@ module Mixpanel
     #     # tracker has all of the methods of Mixpanel::Events
     #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
     #
-    def initialize(token, error_handler=nil, &block)
+    def initialize(token, error_handler=nil, credentials: nil, &block)
       @token = token
       @error_handler = error_handler || ErrorHandler.new
+      @credentials = credentials
+
+      if block && credentials
+        warn '[WARNING] credentials passed to Events/Tracker are ignored when a custom sink block is provided. Pass credentials to your consumer directly.'
+      end
 
       if block
         @sink = block
       else
-        consumer = Consumer.new
+        consumer = Consumer.new(credentials: credentials)
         @sink = consumer.method(:send!)
       end
     end
@@ -87,19 +92,66 @@ module Mixpanel
     # we pass the time of the method call as the time the event occured, if you
     # wish to override this pass a timestamp in the properties hash.
     #
-    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
-    #
-    #     # Track that user "12345"'s credit card was declined
-    #     tracker.import("API_KEY", "12345", "Credit Card Declined")
-    #
-    #     # Properties describe the circumstances of the event,
-    #     # or aspects of the source or user associated with the event
-    #     tracker.import("API_KEY", "12345", "Welcome Email Sent", {
+    #     # Recommended: Use import_events() instead
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #     tracker.import_events("12345", "Welcome Email Sent", {
     #         'Email Template' => 'Pretty Pink Welcome',
     #         'User Sign-up Cohort' => 'July 2013',
     #         'time' => 1369353600,
     #     })
+    #
+    #     # Legacy: Pass API key as first parameter (deprecated)
+    #     tracker.import("API_KEY", "12345", "Credit Card Declined")
+    #
     def import(api_key, distinct_id, event, properties={}, ip=nil)
+      # Warn about deprecated API key usage
+      if api_key && !api_key.to_s.empty?
+        warn '[DEPRECATION] Passing api_key to import() is deprecated. Use ServiceAccountCredentials in the constructor instead. See https://docs.mixpanel.com/docs/tracking-methods/sdks/ruby#service-account-authentication'
+      end
+
+      # Warn when using import(nil, ...) - recommend import_events instead
+      if api_key.nil? && @credentials
+        warn '[DEPRECATION] Using import(nil, ...) is deprecated. Use import_events(...) instead for cleaner API.'
+      end
+
+      # Delegate to internal implementation
+      import_internal(api_key, distinct_id, event, properties, ip)
+    end
+
+    # Import an event using service account credentials from the constructor.
+    # This is the recommended method for importing historical events with service accounts.
+    #
+    # Credentials must be provided in the Tracker/Events constructor. This method is cleaner
+    # than import() as it doesn't require passing nil as the first parameter.
+    #
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #
+    #     tracker.import_events('user123', 'Past Event', {
+    #         'time' => 1369353600,
+    #         'Source' => 'Import'
+    #     })
+    #
+    def import_events(distinct_id, event, properties={}, ip=nil)
+      unless @credentials
+        raise ArgumentError, 'import_events requires credentials in constructor. Use: Tracker.new(token, credentials: credentials)'
+      end
+
+      # Delegate to internal implementation with nil api_key (uses constructor credentials)
+      import_internal(nil, distinct_id, event, properties, ip)
+    end
+
+    private
+
+    # Internal implementation for importing events.
+    # Called by both import() and import_events().
+    def import_internal(api_key, distinct_id, event, properties, ip)
+      # Validate that at least one authentication method is provided
+      if api_key.nil? && @credentials.nil?
+        raise ArgumentError, 'import requires authentication: provide either api_key parameter or credentials in constructor'
+      end
+
       properties = {
         'distinct_id' => distinct_id,
         'token' => @token,
@@ -116,9 +168,15 @@ module Mixpanel
 
       message = {
         'data' => data,
-        'api_key' => api_key,
       }
 
+      # Only include api_key in message if provided (legacy auth)
+      # When using service account credentials (recommended), pass nil for api_key
+      # and the Consumer will use credentials from its instance variable
+      if api_key
+        message['api_key'] = api_key
+      end
+
       ret = true
       begin
         @sink.call(:import, message.to_json)

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

@@ -12,7 +12,7 @@ module Mixpanel
     # 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 provider_config [Hash] Configuration with :token, :api_host, :request_timeout_in_seconds, :exposure_executor, :credentials (optional)
       # @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'
@@ -23,6 +23,8 @@ module Mixpanel
         @tracker_callback = tracker_callback
         @evaluation_mode = evaluation_mode
         @error_handler = error_handler
+        @exposure_executor = provider_config[:exposure_executor]
+        @credentials = provider_config[:credentials]
       end
 
       # Make HTTP request to flags API endpoint
@@ -31,12 +33,20 @@ module Mixpanel
       # @raise [Mixpanel::ConnectionError] on network errors
       # @raise [Mixpanel::ServerError] on HTTP errors
       def call_flags_endpoint(additional_params = nil)
+        # Always use token in query params
         common_params = Utils.prepare_common_query_params(
           @provider_config[:token],
           Mixpanel::VERSION
         )
 
         params = common_params.merge(additional_params || {})
+
+        # Add project_id as query parameter when using service account credentials
+        # Note: project_id is required for service account auth but not used for token auth
+        if @credentials
+          params['project_id'] = @credentials.project_id
+        end
+
         query_string = URI.encode_www_form(params)
 
         uri = URI::HTTPS.build(
@@ -53,7 +63,12 @@ module Mixpanel
 
         request = Net::HTTP::Get.new(uri.request_uri)
 
-        request.basic_auth(@provider_config[:token], '')
+        # Use service account credentials for basic auth if provided, otherwise use token
+        if @credentials
+          request.basic_auth(@credentials.username, @credentials.secret)
+        else
+          request.basic_auth(@provider_config[:token], '')
+        end
 
         request['Content-Type'] = 'application/json'
         request['traceparent'] = Utils.generate_traceparent
@@ -88,6 +103,14 @@ module Mixpanel
         distinct_id = context['distinct_id'] || context[:distinct_id]
 
         unless distinct_id
+          # Local eval succeeds when the flag's Variant Assignment Key is
+          # something other than distinct_id (e.g., device_id), but the
+          # exposure event still needs distinct_id to attribute the user.
+          # Surface the drop instead of silently returning so callers can
+          # see they need to include distinct_id in the context.
+          @error_handler&.handle(MixpanelError.new(
+            "Cannot track exposure event for flag '#{flag_key}' without a distinct_id in the context"
+          ))
           return
         end
 
@@ -104,12 +127,40 @@ module Mixpanel
         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)
+        dispatch_exposure(distinct_id, properties)
+      end
+
+      private
+
+      # Dispatch the tracker call inline or via the configured executor.
+      # The executor is duck-typed — anything that responds to #post(&block)
+      # works (Concurrent::ExecutorService, or a Thread.new wrapper).
+      #
+      # Async path only: catch any non-MixpanelError from the tracker so it
+      # doesn't terminate the executor thread silently. Inline path
+      # preserves the original behavior — non-MixpanelError propagates to
+      # the flag evaluator's caller unchanged.
+      def dispatch_exposure(distinct_id, properties)
+        if @exposure_executor
+          begin
+            @exposure_executor.post do
+              invoke_tracker(distinct_id, properties)
+            rescue StandardError => e
+              @error_handler.handle(MixpanelError.new("Exposure event failed: #{e.class}: #{e.message}")) if @error_handler
+            end
+          rescue StandardError => e
+            @error_handler.handle(MixpanelError.new("Exposure event dropped — executor refused to accept task: #{e.message}")) if @error_handler
+          end
+        else
+          invoke_tracker(distinct_id, properties)
         end
       end
+
+      def invoke_tracker(distinct_id, properties)
+        @tracker_callback.call(distinct_id, Utils::EXPOSURE_EVENT, properties)
+      rescue MixpanelError => e
+        @error_handler.handle(e) if @error_handler
+      end
     end
   end
 end

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

@@ -11,20 +11,35 @@ module Mixpanel
         api_host: 'api.mixpanel.com',
         request_timeout_in_seconds: 10,
         enable_polling: true,
-        polling_interval_in_seconds: 60
+        polling_interval_in_seconds: 60,
+        exposure_executor: nil
       }.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 || {})
+      # @param credentials [ServiceAccountCredentials, nil] Optional service account credentials
+      def initialize(token, config, tracker_callback, error_handler, credentials = nil)
+        # compact: an explicit nil from the caller (e.g.
+        # polling_interval_in_seconds: nil) must not override a sane default.
+        # Both the previous sleep(nil) and the current
+        # ConditionVariable#wait(mutex, nil) block indefinitely, which would
+        # silently disable polling — fall back to the default instead.
+        @config = DEFAULT_CONFIG.merge((config || {}).compact)
+
+        interval = @config[:polling_interval_in_seconds]
+        unless interval.is_a?(Numeric) && interval > 0
+          raise ArgumentError,
+                "polling_interval_in_seconds must be a positive number, got: #{interval.inspect}"
+        end
 
         provider_config = {
           token: token,
           api_host: @config[:api_host],
-          request_timeout_in_seconds: @config[:request_timeout_in_seconds]
+          request_timeout_in_seconds: @config[:request_timeout_in_seconds],
+          exposure_executor: @config[:exposure_executor],
+          credentials: credentials
         }
 
         super(provider_config, '/flags/definitions', tracker_callback, 'local', error_handler)
@@ -32,36 +47,90 @@ module Mixpanel
         @flag_definitions = {}
         @polling_thread = nil
         @stop_polling = false
+        @polling_mutex = Mutex.new
+        @polling_condition = ConditionVariable.new
+        # Separate from @polling_mutex: serializes the full start/stop lifecycle
+        # (including the join inside stop) so a concurrent start can't observe a
+        # mid-stop state and spawn a new polling thread before the old one
+        # finishes exiting. We can't hold @polling_mutex across the join — the
+        # polling thread needs it to wake from the condition wait.
+        @lifecycle_mutex = Mutex.new
       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
+        # Clear @stop_polling BEFORE the initial fetch so a concurrent
+        # stop_polling_for_definitions! arriving during the fetch can flip it
+        # back to true and signal "abandon start". Under @polling_mutex, writes
+        # to @stop_polling are linearized: whichever of {start's clear, stop's
+        # set} happened latest is what we observe under the lifecycle lock
+        # below — i.e. last-writer-wins semantics preserve stop's postcondition
+        # (polling is off when stop returns) even across the unguarded fetch.
+        @polling_mutex.synchronize { @stop_polling = false }
+
+        # Initial fetch is intentionally outside @lifecycle_mutex: it's a
+        # blocking HTTP call, and holding the lifecycle lock across it would
+        # block a concurrent stop_polling_for_definitions! for the full request
+        # timeout.
+        #
+        # A transient failure here (network blip, HTTP 500) should NOT prevent
+        # the polling thread from spawning — the loop retries on the configured
+        # interval. Without this inner rescue, the outer rescue below would
+        # catch and return, leaving the SDK permanently without polling until
+        # the caller manually retried.
+        begin
+          fetch_flag_definitions
+        rescue StandardError => e
+          safe_handle_error(e)
+        end
+
+        @lifecycle_mutex.synchronize do
+          # If a stop arrived during/after our @stop_polling clear above, abort
+          # — the user's stop "wins" because it's the most recent intent.
+          stop_requested = @polling_mutex.synchronize { @stop_polling }
+
+          # .alive? guards against a prior polling thread that died abnormally
+          # (e.g. error_handler itself raised); without it @polling_thread would
+          # be non-nil-but-dead and we'd silently refuse to restart polling.
+          if !stop_requested && @config[:enable_polling] &&
+             (@polling_thread.nil? || !@polling_thread.alive?)
+            @polling_thread = Thread.new do
+              loop do
+                # Check @stop_polling INSIDE the mutex (before and after wait)
+                # so a broadcast from stop_polling_for_definitions! can't be
+                # lost if it arrives while we're outside the synchronized region
+                # (e.g. during fetch_flag_definitions below).
+                stopped = @polling_mutex.synchronize do
+                  next true if @stop_polling
+
+                  @polling_condition.wait(@polling_mutex, @config[:polling_interval_in_seconds])
+                  @stop_polling
+                end
+                break if stopped
+
+                begin
+                  fetch_flag_definitions
+                rescue StandardError => e
+                  safe_handle_error(e)
+                end
               end
             end
           end
         end
       rescue StandardError => e
-        @error_handler.handle(e) if @error_handler
+        safe_handle_error(e)
       end
 
       def stop_polling_for_definitions!
-        @stop_polling = true
-        @polling_thread&.join
-        @polling_thread = nil
+        @lifecycle_mutex.synchronize do
+          @polling_mutex.synchronize do
+            @stop_polling = true
+            @polling_condition.broadcast
+          end
+          @polling_thread&.join
+          @polling_thread = nil
+        end
       end
 
       def shutdown
@@ -102,11 +171,11 @@ module Mixpanel
       def get_variant(flag_key, fallback_variant, context, report_exposure: true)
         flag = @flag_definitions[flag_key]
 
-        return fallback_variant unless flag
+        return fallback_variant.as_fallback(FallbackReason.flag_not_found) unless flag
 
         context_key = flag['context']
         unless context.key?(context_key) || context.key?(context_key.to_sym)
-          return fallback_variant
+          return fallback_variant.as_fallback(FallbackReason.missing_context_key(context_key))
         end
 
         context_value = context[context_key] || context[context_key.to_sym]
@@ -118,10 +187,10 @@ module Mixpanel
           selected_variant = get_assigned_variant(flag, context_value, flag_key, rollout) if rollout
         end
 
-        return fallback_variant unless selected_variant
+        return fallback_variant.as_fallback(FallbackReason.no_rollout_match) unless selected_variant
 
         track_exposure_event(flag_key, selected_variant, context) if report_exposure
-        selected_variant
+        selected_variant.with_source(VariantSource::LOCAL)
       end
 
       # Get all variants for user context
@@ -130,10 +199,11 @@ module Mixpanel
       # @return [Hash] Map of flag_key => SelectedVariant
       def get_all_variants(context)
         variants = {}
+        fallback = SelectedVariant.new(variant_value: nil)
 
         @flag_definitions.each_key do |flag_key|
-          variant = get_variant(flag_key, nil, context, report_exposure: false)
-          variants[flag_key] = variant if variant
+          variant = get_variant(flag_key, fallback, context, report_exposure: false)
+          variants[flag_key] = variant if variant.variant_source == VariantSource::LOCAL
         end
 
         variants
@@ -141,6 +211,24 @@ module Mixpanel
 
       private
 
+      # Wrap @error_handler.handle so a misbehaving handler can't kill the
+      # polling thread mid-loop — that would leave @polling_thread non-nil but
+      # dead, and (without the .alive? check in start) silently prevent restart.
+      #
+      # Always warn to stderr as well. The default Mixpanel::ErrorHandler#handle
+      # is a no-op, so dispatching only via @error_handler swallows schema drift
+      # (NoMethodError, JSON::ParserError, etc.) — the loop runs forever
+      # undetected. Matches the convention in mixpanel-python / mixpanel-java /
+      # mixpanel-go / mixpanel-node, all of which log unconditionally and keep
+      # polling.
+      def safe_handle_error(error)
+        warn "[Mixpanel] Failed to fetch flag definitions: #{error.class}: #{error.message}"
+        @error_handler.handle(error) if @error_handler
+      rescue StandardError
+        # Swallow handler failures: keeping the polling loop alive is more
+        # important than propagating a broken handler's failure.
+      end
+
       def fetch_flag_definitions
         response = call_flags_endpoint