launchdarkly-server-sdk 8.11.1 → 8.11.3

data/lib/ldclient-rb/impl/data_system/protocolv2.rb

@@ -0,0 +1,264 @@
+require 'json'
+
+module LaunchDarkly
+  module Impl
+    module DataSystem
+      module ProtocolV2
+        #
+        # This module contains the protocol definitions and data types for the
+        # LaunchDarkly data system version 2 (FDv2).
+        #
+
+        #
+        # DeleteObject specifies the deletion of a particular object.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class DeleteObject
+          # @return [Integer] The version
+          attr_reader :version
+
+          # @return [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          attr_reader :kind
+
+          # @return [String] The key
+          attr_reader :key
+
+          #
+          # @param version [Integer] The version
+          # @param kind [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          # @param key [String] The key
+          #
+          def initialize(version:, kind:, key:)
+            @version = version
+            @kind = kind
+            @key = key
+          end
+
+          #
+          # Returns the event name.
+          #
+          # @return [String]
+          #
+          def name
+            LaunchDarkly::Interfaces::DataSystem::EventName::DELETE_OBJECT
+          end
+
+          #
+          # Serializes the DeleteObject to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              version: @version,
+              kind: @kind,
+              key: @key,
+            }
+          end
+
+          #
+          # Deserializes a DeleteObject from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [DeleteObject]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            version = data[:version]
+            kind = data[:kind]
+            key = data[:key]
+
+            raise ArgumentError, "Missing required fields in DeleteObject" if version.nil? || kind.nil? || key.nil?
+
+            new(version: version, kind: kind, key: key)
+          end
+        end
+
+        #
+        # PutObject specifies the addition of a particular object with upsert semantics.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class PutObject
+          # @return [Integer] The version
+          attr_reader :version
+
+          # @return [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          attr_reader :kind
+
+          # @return [String] The key
+          attr_reader :key
+
+          # @return [Hash] The object data
+          attr_reader :object
+
+          #
+          # @param version [Integer] The version
+          # @param kind [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          # @param key [String] The key
+          # @param object [Hash] The object data
+          #
+          def initialize(version:, kind:, key:, object:)
+            @version = version
+            @kind = kind
+            @key = key
+            @object = object
+          end
+
+          #
+          # Returns the event name.
+          #
+          # @return [String]
+          #
+          def name
+            LaunchDarkly::Interfaces::DataSystem::EventName::PUT_OBJECT
+          end
+
+          #
+          # Serializes the PutObject to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              version: @version,
+              kind: @kind,
+              key: @key,
+              object: @object,
+            }
+          end
+
+          #
+          # Deserializes a PutObject from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [PutObject]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            version = data[:version]
+            kind = data[:kind]
+            key = data[:key]
+            object_data = data[:object]
+
+            raise ArgumentError, "Missing required fields in PutObject" if version.nil? || kind.nil? || key.nil? || object_data.nil?
+
+            new(version: version, kind: kind, key: key, object: object_data)
+          end
+        end
+
+        #
+        # Goodbye represents a goodbye event.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class Goodbye
+          # @return [String] The reason for goodbye
+          attr_reader :reason
+
+          # @return [Boolean] Whether the goodbye is silent
+          attr_reader :silent
+
+          # @return [Boolean] Whether this represents a catastrophic failure
+          attr_reader :catastrophe
+
+          #
+          # @param reason [String] The reason for goodbye
+          # @param silent [Boolean] Whether the goodbye is silent
+          # @param catastrophe [Boolean] Whether this represents a catastrophic failure
+          #
+          def initialize(reason:, silent:, catastrophe:)
+            @reason = reason
+            @silent = silent
+            @catastrophe = catastrophe
+          end
+
+          #
+          # Serializes the Goodbye to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              reason: @reason,
+              silent: @silent,
+              catastrophe: @catastrophe,
+            }
+          end
+
+          #
+          # Deserializes a Goodbye event from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [Goodbye]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            reason = data[:reason]
+            silent = data[:silent]
+            catastrophe = data[:catastrophe]
+
+            raise ArgumentError, "Missing required fields in Goodbye" if reason.nil? || silent.nil? || catastrophe.nil?
+
+            new(reason: reason, silent: silent, catastrophe: catastrophe)
+          end
+        end
+
+        #
+        # Error represents an error event.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class Error
+          # @return [String] The payload ID
+          attr_reader :payload_id
+
+          # @return [String] The reason for the error
+          attr_reader :reason
+
+          #
+          # @param payload_id [String] The payload ID
+          # @param reason [String] The reason for the error
+          #
+          def initialize(payload_id:, reason:)
+            @payload_id = payload_id
+            @reason = reason
+          end
+
+          #
+          # Serializes the Error to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              payloadId: @payload_id,
+              reason: @reason,
+            }
+          end
+
+          #
+          # Deserializes an Error from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [Error]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            payload_id = data[:payloadId]
+            reason = data[:reason]
+
+            raise ArgumentError, "Missing required fields in Error" if payload_id.nil? || reason.nil?
+
+            new(payload_id: payload_id, reason: reason)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-rb/impl/data_system.rb

@@ -0,0 +1,298 @@
+module LaunchDarkly
+  module Impl
+    #
+    # Mixin that defines the required methods of a data system implementation. The data system
+    # is responsible for managing the SDK's data model, including storage, retrieval, and change
+    # detection for feature flag configurations.
+    #
+    # This module also contains supporting classes and additional mixins for data system
+    # implementations, such as DataAvailability, Update, and protocol-specific mixins.
+    #
+    # For operations that can fail, use {LaunchDarkly::Result} from util.rb.
+    #
+    # Application code should not need to implement this directly; it is used internally by the
+    # SDK's data system implementations.
+    #
+    # @private
+    #
+    module DataSystem
+      #
+      # Starts the data system.
+      #
+      # This method will return immediately. The returned event will be set when the system
+      # has reached an initial state (either permanently failed, e.g. due to bad auth, or succeeded).
+      #
+      # If called multiple times, returns the same event as the first call.
+      #
+      # @return [Concurrent::Event] Event that will be set when initialization is complete
+      #
+      def start
+        raise NotImplementedError, "#{self.class} must implement #start"
+      end
+
+      #
+      # Halts the data system. Should be called when the client is closed to stop any long running
+      # operations. Makes the data system no longer usable.
+      #
+      # @return [void]
+      #
+      def stop
+        raise NotImplementedError, "#{self.class} must implement #stop"
+      end
+
+      #
+      # Returns an interface for tracking the status of the data source.
+      #
+      # The data source is the mechanism that the SDK uses to get feature flag configurations, such
+      # as a streaming connection (the default) or poll requests.
+      #
+      # @return [LaunchDarkly::Interfaces::DataSource::StatusProvider]
+      #
+      def data_source_status_provider
+        raise NotImplementedError, "#{self.class} must implement #data_source_status_provider"
+      end
+
+      #
+      # Returns an interface for tracking the status of a persistent data store.
+      #
+      # The provider has methods for checking whether the data store is (as far
+      # as the SDK knows) currently operational, tracking changes in this
+      # status, and getting cache statistics. These are only relevant for a
+      # persistent data store; if you are using an in-memory data store, then
+      # this method will return a stub object that provides no information.
+      #
+      # @return [LaunchDarkly::Interfaces::DataStore::StatusProvider]
+      #
+      def data_store_status_provider
+        raise NotImplementedError, "#{self.class} must implement #data_store_status_provider"
+      end
+
+      #
+      # Returns the broadcaster for flag change notifications.
+      #
+      # Consumers can use this broadcaster to build their own flag tracker
+      # or listen for flag changes directly.
+      #
+      # @return [LaunchDarkly::Impl::Broadcaster]
+      #
+      def flag_change_broadcaster
+        raise NotImplementedError, "#{self.class} must implement #flag_change_broadcaster"
+      end
+
+      #
+      # Indicates what form of data is currently available.
+      #
+      # This is calculated dynamically based on current system state.
+      #
+      # @return [Symbol] one of the {DataAvailability} constants
+      #
+      def data_availability
+        raise NotImplementedError, "#{self.class} must implement #data_availability"
+      end
+
+      #
+      # Indicates the ideal form of data attainable given the current configuration.
+      #
+      # @return [Symbol] one of the {#DataAvailability} constants
+      #
+      def target_availability
+        raise NotImplementedError, "#{self.class} must implement #target_availability"
+      end
+
+      #
+      # Returns the data store used by the data system.
+      #
+      # @return [Object] The read-only store
+      #
+      def store
+        raise NotImplementedError, "#{self.class} must implement #store"
+      end
+
+      #
+      # Sets the diagnostic accumulator for streaming initialization metrics.
+      # This should be called before start() to ensure metrics are collected.
+      #
+      # @param diagnostic_accumulator [DiagnosticAccumulator] The diagnostic accumulator
+      # @return [void]
+      #
+      def set_diagnostic_accumulator(diagnostic_accumulator)
+        raise NotImplementedError, "#{self.class} must implement #set_diagnostic_accumulator"
+      end
+
+      #
+      # Represents the availability of data in the SDK.
+      #
+      class DataAvailability
+        # The SDK has no data and will evaluate flags using the application-provided default values.
+        DEFAULTS = :defaults
+
+        # The SDK has data, not necessarily the latest, which will be used to evaluate flags.
+        CACHED = :cached
+
+        # The SDK has obtained, at least once, the latest known data from LaunchDarkly.
+        REFRESHED = :refreshed
+
+        ALL = [DEFAULTS, CACHED, REFRESHED].freeze
+
+        #
+        # Returns whether this availability level is **at least** as good as the other.
+        #
+        # @param [Symbol] self_level The current availability level
+        # @param [Symbol] other The other availability level to compare against
+        # @return [Boolean] true if this availability level is at least as good as the other
+        #
+        def self.at_least?(self_level, other)
+          return true if self_level == other
+          return true if self_level == REFRESHED
+          return true if self_level == CACHED && other == DEFAULTS
+
+          false
+        end
+      end
+
+      #
+      # Mixin that defines the required methods of a diagnostic accumulator implementation.
+      # The diagnostic accumulator is used for collecting and reporting diagnostic events
+      # to LaunchDarkly for monitoring SDK performance and behavior.
+      #
+      # Application code should not need to implement this directly; it is used internally by the SDK.
+      #
+      module DiagnosticAccumulator
+        #
+        # Record a stream initialization.
+        #
+        # @param timestamp [Float] The timestamp
+        # @param duration [Float] The duration
+        # @param failed [Boolean] Whether it failed
+        # @return [void]
+        #
+        def record_stream_init(timestamp, duration, failed)
+          raise NotImplementedError, "#{self.class} must implement #record_stream_init"
+        end
+
+        #
+        # Record events in a batch.
+        #
+        # @param events_in_batch [Integer] The number of events
+        # @return [void]
+        #
+        def record_events_in_batch(events_in_batch)
+          raise NotImplementedError, "#{self.class} must implement #record_events_in_batch"
+        end
+
+        #
+        # Create an event and reset the accumulator.
+        #
+        # @param dropped_events [Integer] The number of dropped events
+        # @param deduplicated_users [Integer] The number of deduplicated users
+        # @return [Object] The diagnostic event
+        #
+        def create_event_and_reset(dropped_events, deduplicated_users)
+          raise NotImplementedError, "#{self.class} must implement #create_event_and_reset"
+        end
+      end
+
+      #
+      # Mixin that defines the required methods for components that can receive a diagnostic accumulator.
+      # Components that include this mixin can report diagnostic information to LaunchDarkly for
+      # monitoring SDK performance and behavior.
+      #
+      # Application code should not need to implement this directly; it is used internally by the SDK.
+      #
+      module DiagnosticSource
+        #
+        # Set the diagnostic_accumulator to be used for reporting diagnostic events.
+        #
+        # @param diagnostic_accumulator [DiagnosticAccumulator] The accumulator
+        # @return [void]
+        #
+        def set_diagnostic_accumulator(diagnostic_accumulator)
+          raise NotImplementedError, "#{self.class} must implement #set_diagnostic_accumulator"
+        end
+      end
+
+      #
+      # Mixin that defines the required methods of an initializer implementation. An initializer
+      # is a component capable of retrieving a single data result, such as from the LaunchDarkly
+      # polling API.
+      #
+      # The intent of initializers is to quickly fetch an initial set of data, which may be stale
+      # but is fast to retrieve. This initial data serves as a foundation for a Synchronizer to
+      # build upon, enabling it to provide updates as new changes occur.
+      #
+      # Application code should not need to implement this directly; it is used internally by the SDK.
+      #
+      module Initializer
+        #
+        # Fetch should retrieve the initial data set for the data source, returning
+        # a Basis object on success, or an error message on failure.
+        #
+        # @return [LaunchDarkly::Result] A Result containing either a Basis or an error message
+        #
+        def fetch
+          raise NotImplementedError, "#{self.class} must implement #fetch"
+        end
+      end
+
+      #
+      # Update represents the results of a synchronizer's ongoing sync method.
+      #
+      class Update
+        # @return [Symbol] The state of the data source
+        attr_reader :state
+
+        # @return [ChangeSet, nil] The change set if available
+        attr_reader :change_set
+
+        # @return [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] Error information if applicable
+        attr_reader :error
+
+        # @return [Boolean] Whether to revert to FDv1
+        attr_reader :revert_to_fdv1
+
+        # @return [String, nil] The environment ID if available
+        attr_reader :environment_id
+
+        #
+        # @param state [Symbol] The state of the data source
+        # @param change_set [ChangeSet, nil] The change set if available
+        # @param error [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] Error information if applicable
+        # @param revert_to_fdv1 [Boolean] Whether to revert to FDv1
+        # @param environment_id [String, nil] The environment ID if available
+        #
+        def initialize(state:, change_set: nil, error: nil, revert_to_fdv1: false, environment_id: nil)
+          @state = state
+          @change_set = change_set
+          @error = error
+          @revert_to_fdv1 = revert_to_fdv1
+          @environment_id = environment_id
+        end
+      end
+
+      #
+      # Mixin that defines the required methods of a synchronizer implementation. A synchronizer
+      # is a component capable of synchronizing data from an external data source, such as a
+      # streaming or polling API.
+      #
+      # It is responsible for yielding Update objects that represent the current state of the
+      # data source, including any changes that have occurred since the last synchronization.
+      #
+      # Application code should not need to implement this directly; it is used internally by the SDK.
+      #
+      module Synchronizer
+        #
+        # Sync should begin the synchronization process for the data source, yielding
+        # Update objects until the connection is closed or an unrecoverable error
+        # occurs.
+        #
+        # @yield [Update] Yields Update objects as synchronization progresses
+        # @return [void]
+        #
+        def sync
+          raise NotImplementedError, "#{self.class} must implement #sync"
+        end
+      end
+    end
+  end
+end
+

data/lib/ldclient-rb/impl/dependency_tracker.rb

@@ -1,9 +1,12 @@
+require "ldclient-rb/impl/model/serialization"
+
 module LaunchDarkly
   module Impl
     class DependencyTracker
-      def initialize
+      def initialize(logger = nil)
         @from = {}
         @to = {}
+        @logger = logger
       end
 
       #
@@ -11,11 +14,11 @@ module LaunchDarkly
       #
       # @param from_kind [Object] the changed item's kind
       # @param from_key [String] the changed item's key
-      # @param from_item [Object] the changed item
+      # @param from_item [Object] the changed item (can be a Hash, model object, or nil)
       #
       def update_dependencies_from(from_kind, from_key, from_item)
         from_what = { kind: from_kind, key: from_key }
-        updated_dependencies = DependencyTracker.compute_dependencies_from(from_kind, from_item)
+        updated_dependencies = DependencyTracker.compute_dependencies_from(from_kind, from_item, @logger)
 
         old_dependency_set = @from[from_what]
         unless old_dependency_set.nil?
@@ -39,7 +42,7 @@ module LaunchDarkly
       def self.segment_keys_from_clauses(clauses)
         clauses.flat_map do |clause|
           if clause.op == :segmentMatch
-            clause.values.map { |value| {kind: LaunchDarkly::SEGMENTS, key: value }}
+            clause.values.map { |value| {kind: DataStore::SEGMENTS, key: value }}
           else
             []
           end
@@ -48,19 +51,28 @@ module LaunchDarkly
 
       #
       # @param from_kind [String]
-      # @param from_item [LaunchDarkly::Impl::Model::FeatureFlag, LaunchDarkly::Impl::Model::Segment]
+      # @param from_item [Hash, LaunchDarkly::Impl::Model::FeatureFlag, LaunchDarkly::Impl::Model::Segment, nil] the item (can be a hash, model object, or nil)
+      # @param logger [Logger, nil] optional logger for deserialization
       # @return [Set]
       #
-      def self.compute_dependencies_from(from_kind, from_item)
-        return Set.new if from_item.nil?
+      def self.compute_dependencies_from(from_kind, from_item, logger = nil)
+        # Check for deleted items (matches Python: from_item.get('deleted', False))
+        return Set.new if from_item.nil? || (from_item.is_a?(Hash) && from_item[:deleted])
+
+        # Deserialize hash to model object if needed (matches Python: from_kind.decode(from_item) if isinstance(from_item, dict))
+        from_item = if from_item.is_a?(Hash)
+                      LaunchDarkly::Impl::Model.deserialize(from_kind, from_item, logger)
+                    else
+                      from_item
+                    end
 
-        if from_kind == LaunchDarkly::FEATURES
+        if from_kind == DataStore::FEATURES && from_item.is_a?(LaunchDarkly::Impl::Model::FeatureFlag)
           prereq_keys = from_item.prerequisites.map { |prereq| {kind: from_kind, key: prereq.key} }
           segment_keys = from_item.rules.flat_map { |rule| DependencyTracker.segment_keys_from_clauses(rule.clauses) }
 
           results = Set.new(prereq_keys)
           results.merge(segment_keys)
-        elsif from_kind == LaunchDarkly::SEGMENTS
+        elsif from_kind == DataStore::SEGMENTS && from_item.is_a?(LaunchDarkly::Impl::Model::Segment)
           kind_and_keys  = from_item.rules.flat_map do |rule|
             DependencyTracker.segment_keys_from_clauses(rule.clauses)
           end

data/lib/ldclient-rb/impl/evaluator.rb

@@ -4,6 +4,7 @@ require "ldclient-rb/impl/evaluator_helpers"
 require "ldclient-rb/impl/evaluator_operators"
 require "ldclient-rb/impl/model/feature_flag"
 require "ldclient-rb/impl/model/segment"
+require "ldclient-rb/impl/util"
 
 module LaunchDarkly
   module Impl
@@ -152,11 +153,11 @@ module LaunchDarkly
         begin
           detail = eval_internal(flag, context, result, state)
         rescue EvaluationException => exn
-          LaunchDarkly::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
+          Impl::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
           result.detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(exn.error_kind))
           return result, state
         rescue => exn
-          LaunchDarkly::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
+          Impl::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
           result.detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
           return result, state
         end

data/lib/ldclient-rb/impl/event_sender.rb

@@ -1,4 +1,5 @@
 require "ldclient-rb/impl/unbounded_pool"
+require "ldclient-rb/impl/util"
 
 require "securerandom"
 require "http"
@@ -21,7 +22,7 @@ module LaunchDarkly
         @logger = config.logger
         @retry_interval = retry_interval
         @http_client_pool = UnboundedPool.new(
-          lambda { LaunchDarkly::Util.new_http_client(@config.events_uri, @config) },
+          lambda { Impl::Util.new_http_client(@config.events_uri, @config) },
           lambda { |client| client.close })
       end
 
@@ -81,9 +82,9 @@ module LaunchDarkly
               end
               return EventSenderResult.new(true, false, res_time)
             end
-            must_shutdown = !LaunchDarkly::Util.http_error_recoverable?(status)
+            must_shutdown = !Impl::Util.http_error_recoverable?(status)
             can_retry = !must_shutdown && attempt == 0
-            message = LaunchDarkly::Util.http_error_message(status, "event delivery", can_retry ? "will retry" : "some events were dropped")
+            message = Impl::Util.http_error_message(status, "event delivery", can_retry ? "will retry" : "some events were dropped")
             @logger.error { "[LDClient] #{message}" }
             if must_shutdown
               return EventSenderResult.new(false, true, nil)