kameleoon-client-ruby 3.21.0 → 3.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea79d87e992d2f5bf9829c8082427c18251101be90f50c769b46242a1f4fc272
-  data.tar.gz: 305d07e5adee2b86cf58acc2b01f8a47f4161daeb06efbc8239e7a585ec355cd
+  metadata.gz: 04efd3ab470f352395de3161c329086e07893f9a29d2e8d55085cc4ab00788c3
+  data.tar.gz: 62d498e4f19ec285358b29672d622e0476e70ae31cbf39bd480bf33dbe5b335b
 SHA512:
-  metadata.gz: c3319b271cf4053f01e9fab40b0133cd609a800f55fd3de84f19b76209d2fcbe5438672aa24a42dc39c1dd4dade97641956c2cff1f5c5c0cee8ece0d80636ca8
-  data.tar.gz: 10dfdd35cf97d0adb20ed4a866c4b6739be6ec11458c267a550bf02f6e5ae2542b282b2c30ac33ae94797e3e4a8ce8dd6187406ef1d85603c2d02d0b9f09d44f
+  metadata.gz: 0431f162cc71fb10db0c3920bef2a9d04c35713dfdfd467fc750ac16345c3cfd5965b8abb17c335ad8a7e7226d85c776a14d5d76030c7173969b00a61b309fd1
+  data.tar.gz: 683b9a9e65838df67344bc3b5ff05d8b04eb37fe5328ec4532f4d18b141d9957ca6709b3373adc22ce4f52791d3d0e90be8927693acfe159add2ba991812dc16

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/configuration/custom_data_info.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'set'
 require 'kameleoon/logging/kameleoon_logger'
 
 module Kameleoon

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/hybrid/manager.rb

@@ -17,7 +17,7 @@ module Kameleoon
       end
     end
 
-    # Implementation of Cache with auto cleaning feature
+    # Implementation of Manager with auto-expiring visitor variations
     class ManagerImpl < Manager
       def initialize(expiration_time, data_manager)
         super()