kameleoon-client-ruby 3.21.0 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea79d87e992d2f5bf9829c8082427c18251101be90f50c769b46242a1f4fc272
-  data.tar.gz: 305d07e5adee2b86cf58acc2b01f8a47f4161daeb06efbc8239e7a585ec355cd
+  metadata.gz: 7f492badef67f0b4e09561d3a3d423e4497dbd7efe22d07641cac9485fe9e100
+  data.tar.gz: 95f7268b78ecd64bd4707c8fc8581251b8f07038a32eb044aebdb0b1cab652b6
 SHA512:
-  metadata.gz: c3319b271cf4053f01e9fab40b0133cd609a800f55fd3de84f19b76209d2fcbe5438672aa24a42dc39c1dd4dade97641956c2cff1f5c5c0cee8ece0d80636ca8
-  data.tar.gz: 10dfdd35cf97d0adb20ed4a866c4b6739be6ec11458c267a550bf02f6e5ae2542b282b2c30ac33ae94797e3e4a8ce8dd6187406ef1d85603c2d02d0b9f09d44f
+  metadata.gz: 194b5aeee439890f068abe5b0b4c0f11fb508844de81e54e5b5582cefed5c7849d17054cb469994b57244177b61b9cfb89ccfecf771d9c135cc7126a277140e8
+  data.tar.gz: 114ecb570390aa32386abf7074463d903884d6faadf8c7b3de77953bc38152dc70cdf3eb7d5d8ac64de127014f318a2d2e53359c830cb9af5d8f3118d581b8d7

data/lib/kameleoon/client_readiness.rb

@@ -1,50 +1,138 @@
 # frozen_string_literal: true
 
 require 'concurrent'
+require 'timeout'
+require 'kameleoon/exceptions'
 
 module Kameleoon
-  # ClientReadiness is a cross-thread latch signalling that the SDK has
-  # successfully loaded its configuration.
+  # ClientReadiness tracks whether the SDK has successfully loaded its configuration
+  # and exposes that state to `KameleoonClient#wait_init` and `KameleoonClient#is_ready?`:
+  # - a successful fetch settles the state successfully;
+  # - a failed fetch settles it with an `Exception::Initialization` error.
   #
-  # It is created on the thread that builds the client but released (`set`) from
-  # the background thread(s) performing configuration fetches, so it relies on
-  # Concurrent::Event (which allows cross-thread release) rather than a
-  # read/write lock (whose write lock must be released by the acquiring thread).
+  # Readiness is monotonic: once the SDK is ready it stays ready, and a later failed fetch
+  # can never revert it. A failure reported before the first success does not prevent a
+  # subsequent successful retry from marking the SDK ready.
   #
-  # A failed fetch does NOT release the latch: the client keeps retrying in the
-  # background and the latch is released as soon as any fetch succeeds. Callers
-  # should bound their `wait` with a timeout so they are never blocked forever
-  # when the configuration can never be loaded.
+  # It is created on the thread that builds the client but settled from the background
+  # thread(s) performing configuration fetches, so it relies on Concurrent::Event
+  # (which allows cross-thread release).
   class ClientReadiness
-    def initialize
-      @success = false
-      @event = Concurrent::Event.new
+    # State is a single settlement of the readiness state: `error` is written at most
+    # once, before the event is set, and never changes afterwards, so a waiter which
+    # obtained the state observes exactly the outcome it was registered for.
+    class State
+      attr_accessor :error
+
+      def initialize
+        @event = Concurrent::Event.new
+        @error = nil
+      end
+
+      def settle
+        @event.set
+      end
+
+      def settled?
+        @event.set?
+      end
+
+      # @return [Boolean] whether the state was settled before the timeout elapsed.
+      def wait(timeout_second)
+        @event.wait(timeout_second)
+      end
     end
+    private_constant :State
 
-    # @return [Boolean] whether the SDK has become ready (configuration loaded).
-    def success
-      @success
+    def initialize(site_code, environment)
+      @mutex = Mutex.new
+      @state = State.new
+      @ready = false
+      @site_code = site_code
+      @environment = environment
     end
 
-    # Record a fetch outcome. A successful fetch marks the client ready and
-    # unblocks all waiting threads; a failed fetch is ignored so that a later
-    # successful retry can still release the latch. Idempotent and safe to call
-    # from any thread.
-    def set(success)
-      return unless success
+    # Marks the SDK ready and releases all waiters.
+    def mark_ready
+      @mutex.synchronize do
+        @ready = true
+        if @state.settled?
+          unless @state.error.nil?
+            # Recovery after a failure: the failed state is left settled for its waiters,
+            # and a fresh, ready state is published for the new ones.
+            state = State.new
+            state.settle
+            @state = state
+          end
+        else
+          @state.settle
+        end
+      end
+    end
+
+    # Reports a failed fetch with an `Exception::Initialization` error, but only while
+    # the SDK is not yet ready. A failure never reverts an already-ready client and is
+    # reported at most once, so the first reported cause is the one waiters observe.
+    #
+    # @param cause [StandardError, nil] the failure which prevented the SDK from
+    #   loading its configuration.
+    def mark_not_ready(cause)
+      @mutex.synchronize do
+        unless @state.settled?
+          @state.error = Exception::Initialization.new(@site_code, @environment, cause)
+          @state.settle
+        end # else: already ready, or the failure was already reported
+      end
+    end
 
-      @success = true
-      @event.set
+    # @return [Boolean] `true` if the SDK has been successfully initialized, `false`
+    #   otherwise (including while the initialization is still pending or has failed).
+    #   It never blocks.
+    #
+    # This is the per-request hot path, so it is lock-free: `@ready` is only ever
+    # flipped false -> true (readiness is monotonic), making a plain ivar read safe.
+    # At worst a reader briefly observes `false` while `mark_ready` is completing,
+    # which is indistinguishable from calling a moment earlier.
+    def ready?
+      @ready
     end
 
-    # Block until the SDK becomes ready or the timeout elapses.
+    # Blocks until the readiness state is settled, but no longer than `timeout_second`.
+    # Returns the result of the configuration fetch: nil once the SDK is ready, or the
+    # `Exception::Initialization` error the fetch failure was reported with (fail-fast -
+    # it does not wait for background retries). If no fetch result is available within
+    # the timeout, returns an `Exception::Initialization` error caused by the expired
+    # timeout. A non-positive timeout expires immediately unless a result is already
+    # available. An expired timeout does not settle the readiness state: once the SDK
+    # becomes ready, a subsequent call returns nil.
     #
-    # @param timeout [Numeric, nil] maximum number of seconds to wait;
-    #   nil waits indefinitely.
-    # @return [Boolean] whether the SDK is ready.
-    def wait(timeout = nil)
-      @event.wait(timeout)
-      @success
+    # @param timeout_second [Numeric] maximum number of seconds to wait.
+    # @return [Kameleoon::Exception::Initialization, nil] nil if the SDK is ready.
+    def wait_with_timeout(timeout_second)
+      state = current_state
+      return state.error if state.settled?
+      return timeout_failure(timeout_second) if timeout_second <= 0
+
+      return state.error if state.wait(timeout_second)
+
+      timeout_failure(timeout_second)
+    end
+
+    private
+
+    # The timeout failure wraps a `Timeout::Error` cause (the counterpart of the
+    # timeout error types the other SDKs report), so a caller can distinguish an
+    # expired timeout from a failed fetch.
+    def timeout_failure(timeout_second)
+      cause = Timeout::Error.new(
+        "initialization did not complete within #{(timeout_second * 1000).round} ms"
+      )
+      Exception::Initialization.new(@site_code, @environment, cause)
+    end
+
+    # Synchronized for safe publication of the state swapped in by a recovery.
+    def current_state
+      @mutex.synchronize { @state }
     end
   end
 end

data/lib/kameleoon/events/data_file_update_event.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  module Events
+    ##
+    # Describes an update of the SDK data file (configuration) reported to `DataFileUpdateHandler`.
+    class DataFileUpdateEvent
+      ##
+      # Source of a data file update.
+      module Source
+        ##
+        # The data file was updated by periodic polling.
+        POLLING = :polling
+
+        ##
+        # The data file was updated by a real-time (streaming) notification.
+        STREAMING = :streaming
+      end
+
+      # @return [Symbol] The source of the data file update, one of the `Source` constants.
+      attr_reader :source
+
+      # @return [Integer] The date of the last modification of the data file,
+      #   in Unix time milliseconds.
+      attr_reader :date_modified
+
+      def initialize(source, date_modified)
+        @source = source
+        @date_modified = date_modified
+      end
+
+      def to_s
+        "DataFileUpdateEvent{source:#{@source},date_modified:#{@date_modified}}"
+      end
+    end
+  end
+end

data/lib/kameleoon/events/data_file_update_handler.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'kameleoon/events/event_handler'
+
+module Kameleoon
+  module Events
+    ##
+    # Handler of `EventType::DATAFILE_UPDATE` SDK events.
+    #
+    # A handler must respond to the following method:
+    #
+    #   # Called when the SDK data file (configuration) is updated.
+    #   #
+    #   # @param event [Kameleoon::Events::DataFileUpdateEvent] The data file update details.
+    #   def on_update(event); end
+    #
+    # Including this module is optional and serves documentation purposes only.
+    module DataFileUpdateHandler
+      include EventHandler
+    end
+  end
+end

data/lib/kameleoon/events/event_handler.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  module Events
+    ##
+    # Base module for all SDK event handlers. See `EventType` for the supported event types
+    # and their corresponding handler modules.
+    #
+    # Including the handler modules is optional: any object which responds to the methods
+    # required by the selected event type is accepted by `KameleoonClient#set_event_handler`.
+    module EventHandler
+    end
+  end
+end

data/lib/kameleoon/events/event_manager.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'kameleoon/events/data_file_update_event'
+require 'kameleoon/events/event_type'
+require 'kameleoon/events/http_request_failure'
+require 'kameleoon/events/request_type'
+require 'kameleoon/logging/kameleoon_logger'
+
+module Kameleoon
+  module Events
+    ##
+    # EventManager stores SDK event handlers and fires SDK events.
+    #
+    # @api private
+    class EventManager
+      HANDLER_METHODS = {
+        EventType::HTTP_REQUEST => %i[on_request_succeeded on_request_failed],
+        EventType::DATAFILE_UPDATE => %i[on_update]
+      }.freeze
+
+      def initialize
+        @event_handlers = {}
+      end
+
+      def set_event_handler(event_type, handler)
+        handler_methods = HANDLER_METHODS[event_type]
+        if handler_methods.nil?
+          Logging::KameleoonLogger.error("Unknown event type '%s'", event_type)
+          return
+        end
+        unless handler.nil? || handler_methods.all? { |method| handler.respond_to?(method) }
+          Logging::KameleoonLogger.error(
+            "Handler for event type '%s' must respond to the following methods: %s",
+            event_type, handler_methods.join(', ')
+          )
+          return
+        end
+        if handler.nil?
+          @event_handlers.delete(event_type)
+        else
+          @event_handlers[event_type] = handler
+        end
+      end
+
+      def fire_http_request_succeeded(request_type, http_status, duration_millis)
+        handler = @event_handlers[EventType::HTTP_REQUEST]
+        return if handler.nil?
+
+        begin
+          handler.on_request_succeeded(request_type, http_status, duration_millis)
+        rescue StandardError => e
+          Logging::KameleoonLogger.warning('HTTP request event handler failed: %s', e)
+        end
+      end
+
+      def fire_http_request_failed(request_type, failure, duration_millis)
+        handler = @event_handlers[EventType::HTTP_REQUEST]
+        return if handler.nil?
+
+        begin
+          handler.on_request_failed(request_type, failure, duration_millis)
+        rescue StandardError => e
+          Logging::KameleoonLogger.warning('HTTP request event handler failed: %s', e)
+        end
+      end
+
+      def fire_data_file_update(event)
+        handler = @event_handlers[EventType::DATAFILE_UPDATE]
+        return if handler.nil?
+
+        begin
+          handler.on_update(event)
+        rescue StandardError => e
+          Logging::KameleoonLogger.warning('Data file update event handler failed: %s', e)
+        end
+      end
+    end
+  end
+end

data/lib/kameleoon/events/event_type.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  module Events
+    ##
+    # SDK event types which can be handled with `KameleoonClient#set_event_handler`.
+    module EventType
+      ##
+      # HTTP request event. Requires a handler implementing the `HttpRequestHandler` methods.
+      HTTP_REQUEST = :http_request
+
+      ##
+      # Data file update event. Requires a handler implementing the `DataFileUpdateHandler` methods.
+      DATAFILE_UPDATE = :datafile_update
+    end
+  end
+end

data/lib/kameleoon/events/http_request_failure.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  module Events
+    ##
+    # Describes the failure of an SDK HTTP request reported to `HttpRequestHandler`.
+    class HttpRequestFailure
+      ##
+      # Reason of an SDK HTTP request failure.
+      module Reason
+        ##
+        # The request completed with an unexpected HTTP status code.
+        HTTP_STATUS = :http_status
+
+        ##
+        # The request failed with an error or exception (e.g. a network error).
+        EXCEPTION = :exception
+
+        ##
+        # The request was cancelled (for example, due to a timeout).
+        CANCELLED = :cancelled
+      end
+
+      # @return [Symbol] The reason of the failure, one of the `Reason` constants.
+      attr_reader :reason
+
+      # @return [Integer, nil] The HTTP status code of the response. Not `nil` only if
+      #   `reason` is `Reason::HTTP_STATUS`.
+      attr_reader :http_status
+
+      # @return [Exception, nil] The exception caused the failure. Not `nil` only if
+      #   `reason` is `Reason::EXCEPTION`.
+      attr_reader :cause
+
+      # @api private
+      def self.from_http_status(http_status)
+        new(Reason::HTTP_STATUS, http_status, nil)
+      end
+
+      # @api private
+      def self.from_exception(cause)
+        new(Reason::EXCEPTION, nil, cause)
+      end
+
+      # @api private
+      def self.of_cancellation
+        new(Reason::CANCELLED, nil, nil)
+      end
+
+      def to_s
+        "HttpRequestFailure{reason:#{@reason},http_status:#{@http_status || 'nil'}," \
+          "cause:#{@cause.nil? ? 'nil' : @cause.class}}"
+      end
+
+      def initialize(reason, http_status, cause)
+        @reason = reason
+        @http_status = http_status
+        @cause = cause
+      end
+      private_class_method :new
+    end
+  end
+end

data/lib/kameleoon/events/http_request_handler.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'kameleoon/events/event_handler'
+
+module Kameleoon
+  module Events
+    ##
+    # Handler of `EventType::HTTP_REQUEST` SDK events. The handler is called once per each
+    # actual HTTP request attempt, including retries.
+    #
+    # A handler must respond to the following methods:
+    #
+    #   # Called when an SDK HTTP request completes successfully.
+    #   #
+    #   # @param request_type [Symbol] The type of the request, one of the `RequestType` constants.
+    #   # @param http_status [Integer] The HTTP status code of the response.
+    #   # @param duration_millis [Integer] The duration of the request in milliseconds.
+    #   def on_request_succeeded(request_type, http_status, duration_millis); end
+    #
+    #   # Called when an SDK HTTP request fails.
+    #   #
+    #   # @param request_type [Symbol] The type of the request, one of the `RequestType` constants.
+    #   # @param failure [Kameleoon::Events::HttpRequestFailure] The failure details.
+    #   # @param duration_millis [Integer] The duration of the request in milliseconds.
+    #   def on_request_failed(request_type, failure, duration_millis); end
+    #
+    # Including this module is optional and serves documentation purposes only.
+    module HttpRequestHandler
+      include EventHandler
+    end
+  end
+end

data/lib/kameleoon/events/request_type.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  module Events
+    ##
+    # Type of an HTTP request performed by the SDK, reported to `HttpRequestHandler`.
+    module RequestType
+      ##
+      # Fetching of the SDK configuration (data file).
+      DATAFILE = :datafile
+
+      ##
+      # Sending of tracking data.
+      TRACKING = :tracking
+
+      ##
+      # Fetching of remote visitor data.
+      REMOTE_VISITOR_DATA = :remote_visitor_data
+
+      ##
+      # Fetching of remote data.
+      REMOTE_DATA = :remote_data
+
+      ##
+      # Fetching of the Kameleoon API access token.
+      ACCESS_TOKEN = :access_token
+    end
+  end
+end

data/lib/kameleoon/exceptions.rb

@@ -70,6 +70,22 @@ module Kameleoon
     class SiteCodeIsEmpty < KameleoonError
     end
 
+    # SDK could not be initialized: its configuration failed to load or no
+    # initialization result was available within the requested timeout.
+    # The failure which prevented the initialization is available via `cause`;
+    # it is also reported in the message so a caller which only logs the
+    # message still learns why the SDK is not initialized.
+    class Initialization < KameleoonError
+      # The failure which prevented the SDK from loading its configuration.
+      attr_reader :cause
+
+      def initialize(site_code, environment, cause)
+        @cause = cause
+        super("SDK is not initialized for siteCode: '#{site_code}', environment: '#{environment}'. " \
+              "Reason: #{cause.nil? ? 'unknown' : cause.message}")
+      end
+    end
+
     # Visitor Code Not Valid (empty or length > 255)
     class VisitorCodeInvalid < KameleoonError
       def initialize(visitor_code)

data/lib/kameleoon/kameleoon_client.rb

@@ -10,6 +10,13 @@ require 'kameleoon/data/manager/assigned_variation'
 require 'kameleoon/data/manager/forced_experiment_variation'
 require 'kameleoon/data/manager/legal_consent'
 require 'kameleoon/data/manager/visitor_manager'
+require 'kameleoon/events/data_file_update_event'
+require 'kameleoon/events/data_file_update_handler'
+require 'kameleoon/events/event_manager'
+require 'kameleoon/events/event_type'
+require 'kameleoon/events/http_request_failure'
+require 'kameleoon/events/http_request_handler'
+require 'kameleoon/events/request_type'
 require 'kameleoon/exceptions'
 require 'kameleoon/hybrid/manager'
 require 'kameleoon/managers/data/data_manager'
@@ -22,7 +29,7 @@ require 'kameleoon/network/activity_event'
 require 'kameleoon/network/network_manager'
 require 'kameleoon/network/url_provider'
 require 'kameleoon/network/cookie/cookie_manager'
-require 'kameleoon/real_time/real_time_configuration_service'
+require 'kameleoon/real_time/real_time_event_service'
 require 'kameleoon/storage/cache_factory'
 require 'kameleoon/targeting/models'
 require 'kameleoon/targeting/targeting_manager'
@@ -58,7 +65,8 @@ module Kameleoon
       @scheduler = Rufus::Scheduler.new
       @site_code = site_code
       @config = config
-      @real_time_configuration_service = nil
+      @disposed = false
+      @real_time_event_service = nil
       @update_configuration_handler = nil
       @fetch_configuration_update_job = nil
       data_file = Configuration::DataFile.new(config.environment, nil)
@@ -67,11 +75,13 @@ module Kameleoon
         @data_manager, config.session_duration_second, @scheduler
       )
       @hybrid_manager = Hybrid::ManagerImpl.new(HYBRID_EXPIRATION_TIME, @data_manager)
+      @event_manager = Events::EventManager.new
       @network_manager = Network::NetworkManager.new(
         config.environment,
         config.default_timeout_millisecond,
         Network::AccessTokenSourceFactory.new(config.client_id, config.client_secret),
-        Network::UrlProvider.new(site_code, config.network_domain)
+        Network::UrlProvider.new(site_code, config.network_domain),
+        @event_manager
       )
       @tracking_manager = Managers::Tracking::TrackingManager.new(
         @data_manager, @network_manager, @visitor_manager, config.tracking_interval_second, @scheduler
@@ -81,7 +91,7 @@ module Kameleoon
         @data_manager, @network_manager, @visitor_manager
       )
       @cookie_manager = Network::Cookie::CookieManager.new(@data_manager, @visitor_manager, config.top_level_domain)
-      @readiness = ClientReadiness.new
+      @readiness = ClientReadiness.new(site_code, config.environment)
       @targeting_manager = Targeting::TargetingManager.new(@data_manager, @visitor_manager)
 
       if @config.verbose_mode == true && Logging::KameleoonLogger.log_level == Logging::LogLevel::WARNING
@@ -95,25 +105,53 @@ module Kameleoon
     ##
     # Block until the SDK has loaded its configuration and is ready to use.
     #
-    # If the initial fetch fails the client keeps retrying in the background, so
-    # this method returns as soon as any fetch succeeds. The wait is always
-    # bounded by a timeout, so it never blocks indefinitely: when the timeout
-    # elapses before the configuration is loaded, the method returns false.
+    # The method returns the result of the configuration fetch: `true` once the
+    # SDK has been initialized, or `false` as soon as the fetch has failed
+    # (without waiting for background retries) or when no fetch result is
+    # available within the timeout. The failure which prevented the SDK from
+    # initializing is reported to the log.
+    #
+    # An expired timeout or a failed fetch does not affect the SDK state: the
+    # client keeps retrying in the background, and once the SDK becomes ready,
+    # a subsequent call returns true.
     #
     # @param [Integer, nil] timeout_millisecond Maximum time to wait, in
     #   milliseconds. When nil or negative, config.default_timeout_millisecond
     #   is applied.
-    # @return [Boolean] true if the SDK is ready, false if the timeout elapsed first.
+    # @return [Boolean] true if the SDK is ready, false if the fetch failed or
+    #   the timeout elapsed first.
     def wait_init(timeout_millisecond = nil)
       Logging::KameleoonLogger.info('CALL: KameleoonClient.wait_init(timeout_millisecond: %s)', timeout_millisecond)
       if timeout_millisecond.nil? || timeout_millisecond.negative?
         timeout_millisecond = @config.default_timeout_millisecond
       end
-      result = @readiness.wait(timeout_millisecond / 1000.0)
+      error = @readiness.wait_with_timeout(timeout_millisecond / 1000.0)
+      if error.nil?
+        Logging::KameleoonLogger.info('Kameleoon is initialized')
+      else
+        Logging::KameleoonLogger.error('Kameleoon failed to initialize due to error: %s', error.message)
+      end
+      result = error.nil?
       Logging::KameleoonLogger.info('RETURN: KameleoonClient.wait_init -> (result: %s)', result)
       result
     end
 
+    ##
+    # Indicates whether the SDK is ready for use, i.e. its configuration has been
+    # successfully loaded. Unlike `wait_init`, it returns immediately without blocking.
+    #
+    # It returns `true` if the SDK has been successfully initialized, `false` otherwise
+    # (including while the initialization is still pending or has failed).
+    #
+    # Readiness is monotonic: once the SDK becomes ready it stays ready.
+    #
+    # @return [Boolean] whether the SDK is ready for use.
+    def is_ready? # rubocop:disable Naming/PredicateName
+      ready = @readiness.ready?
+      Logging::KameleoonLogger.info('CALL/RETURN: KameleoonClient.is_ready? -> (ready: %s)', ready)
+      ready
+    end
+
     ##
     # Obtain a visitor code.
     #
@@ -712,6 +750,24 @@ module Kameleoon
       map_active_features
     end
 
+    ##
+    # Sets the SDK event handler for the specified event type.
+    #
+    # The handler is called when the corresponding SDK event occurs. Supported event types are
+    # defined in `Kameleoon::Events::EventType`. Passing `nil` clears the handler for the
+    # specified event type.
+    #
+    # @param event_type [Symbol] The SDK event type to handle, one of the
+    # `Kameleoon::Events::EventType` constants.
+    # @param handler [Object, nil] The handler to register, or `nil` to remove the current handler.
+    # The handler must respond to the methods required by the selected event type
+    # (see `Kameleoon::Events::HttpRequestHandler` and `Kameleoon::Events::DataFileUpdateHandler`).
+    def set_event_handler(event_type, handler)
+      Logging::KameleoonLogger.info("CALL: KameleoonClient.set_event_handler(event_type: '%s', handler)", event_type)
+      @event_manager.set_event_handler(event_type, handler)
+      Logging::KameleoonLogger.info("RETURN: KameleoonClient.set_event_handler(event_type: '%s', handler)", event_type)
+    end
+
     ##
     # The `on_update_configuration()` method allows you to handle the event when configuration
     # has updated data. It takes one input parameter: callable **handler**. The handler
@@ -719,7 +775,13 @@ module Kameleoon
     #
     # @param handler [Callable | NilClass] The handler that will be called when the configuration
     # is updated using a real-time configuration event.
+    #
+    # DEPRECATED. Please use `set_event_handler(Kameleoon::Events::EventType::DATAFILE_UPDATE, handler)` instead.
     def on_update_configuration(handler)
+      Logging::KameleoonLogger.info(
+        '[DEPRECATION] `on_update_configuration` is deprecated. ' \
+        'Please use `set_event_handler(Kameleoon::Events::EventType::DATAFILE_UPDATE, handler)` instead.'
+      )
       Logging::KameleoonLogger.info('CALL/RETURN: KameleoonClient.on_update_configuration(handler)')
       @update_configuration_handler = handler
     end
@@ -826,44 +888,41 @@ module Kameleoon
 
     HYBRID_EXPIRATION_TIME = 5
 
-    def fetch_configuration_initially
-      Logging::KameleoonLogger.info('Initial configuration fetch is started.')
-      Thread.new do
-        ok = false
-        begin
-          ok = obtain_configuration
-          Logging::KameleoonLogger.error('Initial configuration fetch failed') unless ok
-        rescue StandardError => e
-          Logging::KameleoonLogger.error('Initial configuration fetch failed: %s', e)
-        end
-        @readiness.set(ok)
-        real_time_update = ok && @data_manager.data_file.settings.real_time_update
-        manage_configuration_update(real_time_update)
-      end
-    end
-
+    # Fetches the configuration in a background thread; used for the initial fetch,
+    # the polling schedule, and the streaming events alike. The fetch outcome settles
+    # the client readiness, and a failed fetch always falls back to the polling mode:
+    # a streaming event means the configuration has changed, so staying in the
+    # streaming mode would leave the SDK serving the outdated configuration until
+    # the next event arrives. The server-provided settings are not mutated, so a
+    # later successful fetch switches back to streaming when requested.
     def fetch_configuration_job(time_stamp = nil)
       Thread.new do
+        cause = nil
         ok = false
         begin
           ok = obtain_configuration(time_stamp)
         rescue StandardError => e
+          cause = e
           Logging::KameleoonLogger.error('Error occurred during configuration fetching: %s', e)
         end
-        # Release any threads still waiting in `wait_init` once a (re)fetch
-        # finally succeeds after an unsuccessful initial fetch.
-        @readiness.set(ok)
-        real_time_update = @data_manager.data_file.settings.real_time_update
-        if !ok && real_time_update
-          @data_manager.data_file.settings.real_time_update = false
-          real_time_update = false
-          Logging::KameleoonLogger.warning('Switching to polling mode due to failed fetch')
-        end
-        manage_configuration_update(real_time_update)
+        settle_readiness(ok, cause)
+        manage_configuration_update(ok && @data_manager.data_file.settings.real_time_update)
       end
     end
 
-    def start_configuration_update_job_if_needed
+    # A successful fetch marks the SDK ready, a failed one reports the failure so
+    # `wait_init` fails fast instead of sleeping out its timeout. A failure never
+    # reverts an already-ready client.
+    def settle_readiness(ok, cause)
+      if ok
+        @readiness.mark_ready
+      else
+        cause ||= Exception::KameleoonError.new('configuration fetch failed')
+        @readiness.mark_not_ready(cause)
+      end
+    end
+
+    def start_polling_datafile_update
       return unless @fetch_configuration_update_job.nil?
 
       @fetch_configuration_update_job = @scheduler.schedule_every @config.refresh_interval_second do
@@ -872,7 +931,7 @@ module Kameleoon
       end
     end
 
-    def stop_configuration_update_job_if_needed
+    def stop_polling_datafile_update
       return if @fetch_configuration_update_job.nil?
 
       @fetch_configuration_update_job&.unschedule
@@ -880,27 +939,34 @@ module Kameleoon
       Logging::KameleoonLogger.info('Scheduled job to fetch configuration is stopped.')
     end
 
-    def start_real_time_configuration_service_if_needed
-      return unless @real_time_configuration_service.nil?
+    def start_real_time_event_service_if_needed
+      return unless @real_time_event_service.nil?
 
       url = @network_manager.url_provider.make_real_time_url
       fetch_func = proc { |real_time_event| fetch_configuration_job(real_time_event.time_stamp) }
-      @real_time_configuration_service =
-        Kameleoon::RealTime::RealTimeConfigurationService.new(url, fetch_func)
+      @real_time_event_service =
+        Kameleoon::RealTime::RealTimeEventService.new(url, fetch_func)
     end
 
-    def stop_real_time_configuration_service_if_needed
-      @real_time_configuration_service&.close
-      @real_time_configuration_service = nil
+    def stop_real_time_event_service_if_needed
+      @real_time_event_service&.close
+      @real_time_event_service = nil
     end
 
+    # A disposed client must not (re)start the update services: a fetch which was
+    # in flight when `dispose` ran would otherwise resurrect them. `@disposed` is
+    # set before `dispose` stops the services, so a fetch completing after that
+    # point can only stop things.
     def manage_configuration_update(is_real_time_update)
-      if is_real_time_update
-        stop_configuration_update_job_if_needed
-        start_real_time_configuration_service_if_needed
+      if @disposed
+        stop_polling_datafile_update
+        stop_real_time_event_service_if_needed
+      elsif is_real_time_update
+        stop_polling_datafile_update
+        start_real_time_event_service_if_needed
       else
-        stop_real_time_configuration_service_if_needed
-        start_configuration_update_job_if_needed
+        stop_real_time_event_service_if_needed
+        start_polling_datafile_update
       end
     end
 
@@ -927,34 +993,44 @@ module Kameleoon
       if response.configuration
         configuration = JSON.parse(response.configuration)
         data_file = Configuration::DataFile.new(@config.environment, configuration, response.last_modified)
-        apply_new_configuration(data_file)
-        call_update_handler_if_needed(!time_stamp.nil?)
+        source = time_stamp.nil? ? Events::DataFileUpdateEvent::Source::POLLING
+                                 : Events::DataFileUpdateEvent::Source::STREAMING
+        apply_new_configuration(data_file, source)
         Logging::KameleoonLogger.info('Feature flags are fetched: %s', response.inspect)
       end
       true
     end
 
-    def apply_new_configuration(data_file)
-      Logging::KameleoonLogger.debug('CALL: KameleoonClient.apply_new_configuration(data_file: %s)', data_file)
+    def apply_new_configuration(data_file, source)
+      Logging::KameleoonLogger.debug('CALL: KameleoonClient.apply_new_configuration(data_file: %s, source: %s)',
+                                     data_file, source)
       @data_manager.data_file = data_file
       @network_manager.url_provider.apply_data_api_domain(data_file.settings.data_api_domain)
-      Logging::KameleoonLogger.debug('RETURN: KameleoonClient.apply_new_configuration(data_file: %s)', data_file)
+      @event_manager.fire_data_file_update(Events::DataFileUpdateEvent.new(source, data_file.date_modified))
+      call_deprecated_update_handler if source == Events::DataFileUpdateEvent::Source::STREAMING
+      Logging::KameleoonLogger.debug('RETURN: KameleoonClient.apply_new_configuration(data_file: %s, source: %s)',
+                                     data_file, source)
     end
 
     ##
-    # Call the handler when configuration was updated with new time stamp.
-    #
-    # @param need_call [Bool] Indicates if we need to call handler or not.
-    def call_update_handler_if_needed(need_call)
-      return if !need_call || @update_configuration_handler.nil?
-
-      @update_configuration_handler.call
+    # Call the deprecated update configuration handler when configuration was updated
+    # by a real-time (streaming) notification.
+    def call_deprecated_update_handler
+      handler = @update_configuration_handler
+      return if handler.nil?
+
+      begin
+        handler.call
+      rescue StandardError => e
+        Logging::KameleoonLogger.warning('Update configuration handler failed: %s', e)
+      end
     end
 
     def dispose(_object_id = nil)
       Logging::KameleoonLogger.debug('CALL: KameleoonClient.dispose')
-      stop_configuration_update_job_if_needed
-      stop_real_time_configuration_service_if_needed
+      @disposed = true
+      stop_polling_datafile_update
+      stop_real_time_event_service_if_needed
       @visitor_manager.stop
       @tracking_manager.stop
       @scheduler.shutdown

data/lib/kameleoon/kameleoon_client_factory.rb

@@ -24,7 +24,7 @@ module Kameleoon
       key = get_client_key(site_code, config.environment)
       client = @clients.compute_if_absent(key) do
         client = KameleoonClient.new(site_code, config)
-        client.send(:fetch_configuration_initially)
+        client.send(:fetch_configuration_job)
         client
       end
       Logging::KameleoonLogger.info(

data/lib/kameleoon/network/network_manager.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'kameleoon/events/event_manager'
 require 'kameleoon/logging/kameleoon_logger'
 require 'kameleoon/network/content_type'
 require 'kameleoon/network/fetched_configuration'
@@ -14,8 +15,8 @@ module Kameleoon
     ##
     # NetworkManager is used to make API calls.
     class NetworkManager
-      FETCH_CONFIGURATION_ATTEMPT_NUMBER = 3
-      TRACKING_CALL_ATTEMPT_NUMBER = 3
+      FETCH_CONFIGURATION_ATTEMPT_NUMBER = 2
+      TRACKING_CALL_ATTEMPT_NUMBER = 2
       TRACKING_CALL_RETRY_DELAY = 5.0 # in seconds
       SDK_TYPE_HEADER = 'X-Kameleoon-SDK-Type'
       SDK_VERSION_HEADER = 'X-Kameleoon-SDK-Version'
@@ -23,13 +24,14 @@ module Kameleoon
       HEADER_IF_MODIFIED_SINCE = 'If-Modified-Since'
       HEADER_LAST_MODIFIED = 'last-modified' # in lower case because the network lib casts response headers to lower
 
-      attr_reader :environment, :default_timeout, :access_token_source, :url_provider
+      attr_reader :environment, :default_timeout, :access_token_source, :url_provider, :event_manager
 
-      def initialize(environment, default_timeout, access_token_source_factory, url_provider)
+      def initialize(environment, default_timeout, access_token_source_factory, url_provider, event_manager)
         @environment = environment
         @default_timeout = default_timeout
         @access_token_source = access_token_source_factory.create(self)
         @url_provider = url_provider
+        @event_manager = event_manager
         @sync_net_provider = SyncNetProvider.new
       end
 
@@ -39,7 +41,8 @@ module Kameleoon
         headers = { SDK_TYPE_HEADER => SDK_NAME, SDK_VERSION_HEADER => SDK_VERSION }
         headers[HEADER_IF_MODIFIED_SINCE] = if_modified_since if if_modified_since
         request = Request.new(Method::GET, url, ContentType::JSON, timeout, extra_headers: headers)
-        response, success = make_call(request, false, FETCH_CONFIGURATION_ATTEMPT_NUMBER - 1)
+        response, success = make_call(Events::RequestType::DATAFILE, request, false,
+                                      FETCH_CONFIGURATION_ATTEMPT_NUMBER - 1)
         return nil unless success
         return FetchedConfiguration.new(nil, nil) if response.code == 304
 
@@ -51,14 +54,14 @@ module Kameleoon
         url = @url_provider.make_api_data_get_request_url(key)
         timeout = ensure_timeout(timeout)
         request = Request.new(Method::GET, url, ContentType::JSON, timeout)
-        unwrap_response(*make_call(request, true))
+        unwrap_response(*make_call(Events::RequestType::REMOTE_DATA, request, true))
       end
 
       def get_remote_visitor_data(visitor_code, filter, is_unique_identifier, timeout = nil)
         url = @url_provider.make_visitor_data_get_url(visitor_code, filter, is_unique_identifier)
         timeout = ensure_timeout(timeout)
         request = Request.new(Method::GET, url, ContentType::JSON, timeout)
-        unwrap_response(*make_call(request, true))
+        unwrap_response(*make_call(Events::RequestType::REMOTE_VISITOR_DATA, request, true))
       end
 
       def send_tracking_data(lines, timeout = nil)
@@ -67,7 +70,8 @@ module Kameleoon
         url = @url_provider.make_tracking_url
         timeout = ensure_timeout(timeout)
         request = Request.new(Method::POST, url, ContentType::WILDCARD, timeout, data: lines)
-        unwrap_response(*make_call(request, true, TRACKING_CALL_ATTEMPT_NUMBER - 1, TRACKING_CALL_RETRY_DELAY))
+        unwrap_response(*make_call(Events::RequestType::TRACKING, request, true,
+                                   TRACKING_CALL_ATTEMPT_NUMBER - 1, TRACKING_CALL_RETRY_DELAY))
       end
 
       def fetch_access_jwtoken(basic_auth_token, timeout = nil)
@@ -79,12 +83,12 @@ module Kameleoon
         data = UriHelper.encode_query(data_map).encode('UTF-8')
         request = Request.new(Method::POST, url, ContentType::FORM, timeout, data: data)
         request.authorize(basic_auth_token)
-        unwrap_response(*make_call(request, false))
+        unwrap_response(*make_call(Events::RequestType::ACCESS_TOKEN, request, false))
       end
 
       private
 
-      def make_call(request, try_access_token_auth, retry_limit = 0, retry_delay = 0)
+      def make_call(request_type, request, try_access_token_auth, retry_limit = 0, retry_delay = 0)
         Logging::KameleoonLogger.debug('Running request %s with access token %s, retry limit %s, retry delay %s ms',
                                        request, try_access_token_auth, retry_limit, retry_delay)
         attempt = 0
@@ -93,7 +97,10 @@ module Kameleoon
         while !success && (attempt <= retry_limit)
           delay(retry_delay) if attempt.positive? && retry_delay.positive?
           try_authorize(request) if try_access_token_auth
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
           response = @sync_net_provider.make_request(request)
+          duration_millis = (Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - start_time).round
+          fire_http_request_event(request_type, response, duration_millis)
           if response.success?
             success = true
           elsif !response.error.nil?
@@ -122,6 +129,22 @@ module Kameleoon
         [response, success]
       end
 
+      def fire_http_request_event(request_type, response, duration_millis)
+        if response.success?
+          @event_manager.fire_http_request_succeeded(request_type, response.code, duration_millis)
+        else
+          failure =
+            if response.error.nil?
+              Events::HttpRequestFailure.from_http_status(response.code)
+            elsif response.error.is_a?(Timeout::Error)
+              Events::HttpRequestFailure.of_cancellation
+            else
+              Events::HttpRequestFailure.from_exception(response.error)
+            end
+          @event_manager.fire_http_request_failed(request_type, failure, duration_millis)
+        end
+      end
+
       def get_log_level(attempt, attempt_count)
         attempt < attempt_count ? Logging::LogLevel::WARNING : Logging::LogLevel::ERROR
       end

data/lib/kameleoon/real_time/{real_time_configuration_service.rb → real_time_event_service.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Kameleoon Real Time Configuration Service
+# Kameleoon Real Time Event Service
 
 require 'json'
 require 'kameleoon/logging/kameleoon_logger'
@@ -10,19 +10,24 @@ require 'kameleoon/real_time/sse_client'
 
 module Kameleoon
   module RealTime
-    CONFIGURATION_UPDATE_EVENT = 'configuration-update-event'
+    DATA_FILE_UPDATE_EVENT = 'configuration-update-event'
 
     ##
-    # RealTimeConfigurationService is used for fetching updates of configuration
+    # RealTimeEventService is used for fetching updates of configuration
     # (experiments and feature flags) in real time.
-    class RealTimeConfigurationService
+    class RealTimeEventService
+      # Delay before re-establishing a failed SSE connection, so a persistent
+      # failure does not turn into a hot reconnect loop.
+      RECONNECT_DELAY_SECONDS = 3
+
       ##
       # Parametrized initializer.
       #
       # @param url [String]
       # @param update_handler [Callable[Kameleoon::RealTime::RealTimeEvent] | NilClass] Handler which
       # is synchronously called for gotten RealTimeEvent objects.
-      def initialize(url, update_handler, sse_request_source = nil)
+      # @param reconnect_delay [Numeric] Delay in seconds before a reconnect attempt.
+      def initialize(url, update_handler, sse_request_source = nil, reconnect_delay: RECONNECT_DELAY_SECONDS)
         @url = url
         @update_handler = update_handler
         @need_close = false
@@ -32,6 +37,7 @@ module Kameleoon
           'Connection': 'Keep-Alive'
         }
         @sse_request_source = sse_request_source
+        @reconnect_delay = reconnect_delay
         @sse_thread = nil
         @sse_client = nil
         create_sse_client
@@ -42,7 +48,7 @@ module Kameleoon
       def close
         return if @need_close
 
-        Logging::KameleoonLogger.info('Real-time configuration service is shutting down')
+        Logging::KameleoonLogger.info('Real-time event service is shutting down')
         @need_close = true
         return if @sse_thread.nil?
 
@@ -60,7 +66,7 @@ module Kameleoon
       def init_sse_client
         message_handler = proc do |message|
           Logging::KameleoonLogger.debug("Got SSE event: #{message.event}")
-          if message.event == CONFIGURATION_UPDATE_EVENT
+          if message.event == DATA_FILE_UPDATE_EVENT
             event_dict = JSON.parse(message.data)
             @update_handler&.call(RealTimeEvent.new(event_dict))
           end
@@ -90,6 +96,9 @@ module Kameleoon
           rescue StandardError => e
             Logging::KameleoonLogger.error("Error occurred within SSE client: #{e}")
           end
+          # The delay is applied to every re-establishment (a failed connection and
+          # a dropped stream alike), so a persistent failure cannot produce a hot loop.
+          sleep(@reconnect_delay) unless @need_close
         end
       end
     end

data/lib/kameleoon/targeting/conditions/unknown_condition.rb

@@ -5,11 +5,11 @@ require 'kameleoon/targeting/condition'
 module Kameleoon
   # @api private
   module Targeting
-    # UnknownCondition represents not defined condition, always returns that visitor is targeted (true)
+    # UnknownCondition represents not defined condition, always returns that visitor is not targeted (false)
     class UnknownCondition < Condition
       def check(_data)
-        Logging::KameleoonLogger.warning('Condition of unknown type \'%s\' evaluated as true', type)
-        true
+        Logging::KameleoonLogger.warning('Condition of unknown type \'%s\' evaluated as false', type)
+        false
       end
     end
   end

data/lib/kameleoon/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Kameleoon
-  SDK_VERSION = '3.21.0'
+  SDK_VERSION = '3.22.0'
   SDK_NAME = 'RUBY'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kameleoon-client-ruby
 version: !ruby/object:Gem::Version
-  version: 3.21.0
+  version: 3.22.0
 platform: ruby
 authors:
 - Kameleoon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: em-http-request
@@ -114,6 +114,14 @@ files:
 - lib/kameleoon/data/unique_identifier.rb
 - lib/kameleoon/data/user_agent.rb
 - lib/kameleoon/data/visitor_visits.rb
+- lib/kameleoon/events/data_file_update_event.rb
+- lib/kameleoon/events/data_file_update_handler.rb
+- lib/kameleoon/events/event_handler.rb
+- lib/kameleoon/events/event_manager.rb
+- lib/kameleoon/events/event_type.rb
+- lib/kameleoon/events/http_request_failure.rb
+- lib/kameleoon/events/http_request_handler.rb
+- lib/kameleoon/events/request_type.rb
 - lib/kameleoon/exceptions.rb
 - lib/kameleoon/hybrid/manager.rb
 - lib/kameleoon/kameleoon_client.rb
@@ -141,8 +149,8 @@ files:
 - lib/kameleoon/network/response.rb
 - lib/kameleoon/network/uri_helper.rb
 - lib/kameleoon/network/url_provider.rb
-- lib/kameleoon/real_time/real_time_configuration_service.rb
 - lib/kameleoon/real_time/real_time_event.rb
+- lib/kameleoon/real_time/real_time_event_service.rb
 - lib/kameleoon/real_time/sse_client.rb
 - lib/kameleoon/real_time/sse_message.rb
 - lib/kameleoon/real_time/sse_request.rb