launchdarkly-server-sdk 6.3.0 → 8.0.0

data/lib/ldclient-rb/impl/model/feature_flag.rb

@@ -0,0 +1,255 @@
+require "ldclient-rb/impl/evaluator_helpers"
+require "ldclient-rb/impl/model/clause"
+require "set"
+
+# See serialization.rb for implementation notes on the data model classes.
+
+def check_variation_range(flag, errors_out, variation, description)
+  unless flag.nil? || errors_out.nil? || variation.nil?
+    if variation < 0 || variation >= flag.variations.length
+      errors_out << "#{description} has invalid variation index"
+    end
+  end
+end
+
+module LaunchDarkly
+  module Impl
+    module Model
+      class FeatureFlag
+        # @param data [Hash]
+        # @param logger [Logger|nil]
+        def initialize(data, logger = nil)
+          raise ArgumentError, "expected hash but got #{data.class}" unless data.is_a?(Hash)
+          errors = []
+          @data = data
+          @key = data[:key]
+          @version = data[:version]
+          @deleted = !!data[:deleted]
+          return if @deleted
+          migration_settings = data[:migration] || {}
+          @migration_settings = MigrationSettings.new(migration_settings[:checkRatio])
+          @sampling_ratio = data[:samplingRatio]
+          @exclude_from_summaries = !!data[:excludeFromSummaries]
+          @variations = data[:variations] || []
+          @on = !!data[:on]
+          fallthrough = data[:fallthrough] || {}
+          @fallthrough = VariationOrRollout.new(fallthrough[:variation], fallthrough[:rollout], self, errors, "fallthrough")
+          @off_variation = data[:offVariation]
+          check_variation_range(self, errors, @off_variation, "off variation")
+          @prerequisites = (data[:prerequisites] || []).map do |prereq_data|
+            Prerequisite.new(prereq_data, self, errors)
+          end
+          @targets = (data[:targets] || []).map do |target_data|
+            Target.new(target_data, self, errors)
+          end
+          @context_targets = (data[:contextTargets] || []).map do |target_data|
+            Target.new(target_data, self, errors)
+          end
+          @rules = (data[:rules] || []).map.with_index do |rule_data, index|
+            FlagRule.new(rule_data, index, self, errors)
+          end
+          @salt = data[:salt]
+          @off_result = EvaluatorHelpers.evaluation_detail_for_off_variation(self, EvaluationReason::off)
+          @fallthrough_results = Preprocessor.precompute_multi_variation_results(self,
+              EvaluationReason::fallthrough(false), EvaluationReason::fallthrough(true))
+          unless logger.nil?
+            errors.each do |message|
+              logger.error("[LDClient] Data inconsistency in feature flag \"#{@key}\": #{message}")
+            end
+          end
+        end
+
+        # @return [Hash]
+        attr_reader :data
+        # @return [String]
+        attr_reader :key
+        # @return [Integer]
+        attr_reader :version
+        # @return [Boolean]
+        attr_reader :deleted
+        # @return [MigrationSettings, nil]
+        attr_reader :migration_settings
+        # @return [Integer, nil]
+        attr_reader :sampling_ratio
+        # @return [Boolean, nil]
+        attr_reader :exclude_from_summaries
+        # @return [Array]
+        attr_reader :variations
+        # @return [Boolean]
+        attr_reader :on
+        # @return [Integer|nil]
+        attr_reader :off_variation
+        # @return [LaunchDarkly::Impl::Model::VariationOrRollout]
+        attr_reader :fallthrough
+        # @return [LaunchDarkly::EvaluationDetail]
+        attr_reader :off_result
+        # @return [LaunchDarkly::Impl::Model::EvalResultFactoryMultiVariations]
+        attr_reader :fallthrough_results
+        # @return [Array<LaunchDarkly::Impl::Model::Prerequisite>]
+        attr_reader :prerequisites
+        # @return [Array<LaunchDarkly::Impl::Model::Target>]
+        attr_reader :targets
+        # @return [Array<LaunchDarkly::Impl::Model::Target>]
+        attr_reader :context_targets
+        # @return [Array<LaunchDarkly::Impl::Model::FlagRule>]
+        attr_reader :rules
+        # @return [String]
+        attr_reader :salt
+
+        # This method allows us to read properties of the object as if it's just a hash. Currently this is
+        # necessary because some data store logic is still written to expect hashes; we can remove it once
+        # we migrate entirely to using attributes of the class.
+        def [](key)
+          @data[key]
+        end
+
+        def ==(other)
+          other.is_a?(FeatureFlag) && other.data == self.data
+        end
+
+        def as_json(*) # parameter is unused, but may be passed if we're using the json gem
+          @data
+        end
+
+        # Same as as_json, but converts the JSON structure into a string.
+        def to_json(*a)
+          as_json.to_json(*a)
+        end
+      end
+
+      class Prerequisite
+        def initialize(data, flag, errors_out = nil)
+          @data = data
+          @key = data[:key]
+          @variation = data[:variation]
+          @failure_result = EvaluatorHelpers.evaluation_detail_for_off_variation(flag,
+            EvaluationReason::prerequisite_failed(@key))
+          check_variation_range(flag, errors_out, @variation, "prerequisite")
+        end
+
+        # @return [Hash]
+        attr_reader :data
+        # @return [String]
+        attr_reader :key
+        # @return [Integer]
+        attr_reader :variation
+        # @return [LaunchDarkly::EvaluationDetail]
+        attr_reader :failure_result
+      end
+
+      class Target
+        def initialize(data, flag, errors_out = nil)
+          @kind = data[:contextKind] || LDContext::KIND_DEFAULT
+          @data = data
+          @values = Set.new(data[:values] || [])
+          @variation = data[:variation]
+          @match_result = EvaluatorHelpers.evaluation_detail_for_variation(flag,
+            data[:variation], EvaluationReason::target_match)
+          check_variation_range(flag, errors_out, @variation, "target")
+        end
+
+        # @return [String]
+        attr_reader :kind
+        # @return [Hash]
+        attr_reader :data
+        # @return [Set]
+        attr_reader :values
+        # @return [Integer]
+        attr_reader :variation
+        # @return [LaunchDarkly::EvaluationDetail]
+        attr_reader :match_result
+      end
+
+      class FlagRule
+        def initialize(data, rule_index, flag, errors_out = nil)
+          @data = data
+          @clauses = (data[:clauses] || []).map do |clause_data|
+            Clause.new(clause_data, errors_out)
+          end
+          @variation_or_rollout = VariationOrRollout.new(data[:variation], data[:rollout], flag, errors_out, 'rule')
+          rule_id = data[:id]
+          match_reason = EvaluationReason::rule_match(rule_index, rule_id)
+          match_reason_in_experiment = EvaluationReason::rule_match(rule_index, rule_id, true)
+          @match_results = Preprocessor.precompute_multi_variation_results(flag, match_reason, match_reason_in_experiment)
+        end
+
+        # @return [Hash]
+        attr_reader :data
+        # @return [Array<LaunchDarkly::Impl::Model::Clause>]
+        attr_reader :clauses
+        # @return [LaunchDarkly::Impl::Model::EvalResultFactoryMultiVariations]
+        attr_reader :match_results
+        # @return [LaunchDarkly::Impl::Model::VariationOrRollout]
+        attr_reader :variation_or_rollout
+      end
+
+
+      class MigrationSettings
+        #
+        # @param check_ratio [Int, nil]
+        #
+        def initialize(check_ratio)
+          @check_ratio = check_ratio
+        end
+
+        # @return [Integer, nil]
+        attr_reader :check_ratio
+      end
+
+      class VariationOrRollout
+        def initialize(variation, rollout_data, flag = nil, errors_out = nil, description = nil)
+          @variation = variation
+          check_variation_range(flag, errors_out, variation, description)
+          @rollout = rollout_data.nil? ? nil : Rollout.new(rollout_data, flag, errors_out, description)
+        end
+
+        # @return [Integer|nil]
+        attr_reader :variation
+        # @return [Rollout|nil] currently we do not have a model class for the rollout
+        attr_reader :rollout
+      end
+
+      class Rollout
+        def initialize(data, flag = nil, errors_out = nil, description = nil)
+          @context_kind = data[:contextKind]
+          @variations = (data[:variations] || []).map { |v| WeightedVariation.new(v, flag, errors_out, description) }
+          @bucket_by = data[:bucketBy]
+          @kind = data[:kind]
+          @is_experiment = @kind == "experiment"
+          @seed = data[:seed]
+        end
+
+        # @return [String|nil]
+        attr_reader :context_kind
+        # @return [Array<WeightedVariation>]
+        attr_reader :variations
+        # @return [String|nil]
+        attr_reader :bucket_by
+        # @return [String|nil]
+        attr_reader :kind
+        # @return [Boolean]
+        attr_reader :is_experiment
+        # @return [Integer|nil]
+        attr_reader :seed
+      end
+
+      class WeightedVariation
+        def initialize(data, flag = nil, errors_out = nil, description = nil)
+          @variation = data[:variation]
+          @weight = data[:weight]
+          @untracked = !!data[:untracked]
+          check_variation_range(flag, errors_out, @variation, description)
+        end
+
+        # @return [Integer]
+        attr_reader :variation
+        # @return [Integer]
+        attr_reader :weight
+        # @return [Boolean]
+        attr_reader :untracked
+      end
+
+      # Clause is defined in its own file because clauses are used by both flags and segments
+    end
+  end
+end

data/lib/ldclient-rb/impl/model/preprocessed_data.rb

@@ -0,0 +1,64 @@
+require "ldclient-rb/impl/evaluator_helpers"
+
+module LaunchDarkly
+  module Impl
+    module Model
+      #
+      # Container for a precomputed result that includes a specific variation index and value, an
+      # evaluation reason, and optionally an alternate evaluation reason that corresponds to the
+      # "in experiment" state.
+      #
+      class EvalResultsForSingleVariation
+        def initialize(value, variation_index, regular_reason, in_experiment_reason = nil)
+          @regular_result = EvaluationDetail.new(value, variation_index, regular_reason)
+          @in_experiment_result = in_experiment_reason ?
+            EvaluationDetail.new(value, variation_index, in_experiment_reason) :
+            @regular_result
+        end
+
+        # @param in_experiment [Boolean] indicates whether we want the result to include
+        #   "inExperiment: true" in the reason or not
+        # @return [LaunchDarkly::EvaluationDetail]
+        def get_result(in_experiment = false)
+          in_experiment ? @in_experiment_result : @regular_result
+        end
+      end
+
+      #
+      # Container for a set of precomputed results, one for each possible flag variation.
+      #
+      class EvalResultFactoryMultiVariations
+        def initialize(variation_factories)
+          @factories = variation_factories
+        end
+
+        # @param index [Integer] the variation index
+        # @param in_experiment [Boolean] indicates whether we want the result to include
+        #   "inExperiment: true" in the reason or not
+        # @return [LaunchDarkly::EvaluationDetail]
+        def for_variation(index, in_experiment)
+          if index < 0 || index >= @factories.length
+            EvaluationDetail.new(nil, nil, EvaluationReason.error(EvaluationReason::ERROR_MALFORMED_FLAG))
+          else
+            @factories[index].get_result(in_experiment)
+          end
+        end
+      end
+
+      class Preprocessor
+        # @param flag [LaunchDarkly::Impl::Model::FeatureFlag]
+        # @param regular_reason [LaunchDarkly::EvaluationReason]
+        # @param in_experiment_reason [LaunchDarkly::EvaluationReason]
+        # @return [EvalResultFactoryMultiVariations]
+        def self.precompute_multi_variation_results(flag, regular_reason, in_experiment_reason)
+          factories = []
+          vars = flag[:variations] || []
+          vars.each_index do |index|
+            factories << EvalResultsForSingleVariation.new(vars[index], index, regular_reason, in_experiment_reason)
+          end
+          EvalResultFactoryMultiVariations.new(factories)
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-rb/impl/model/segment.rb

@@ -0,0 +1,132 @@
+require "ldclient-rb/impl/model/clause"
+require "ldclient-rb/impl/model/preprocessed_data"
+require "set"
+
+# See serialization.rb for implementation notes on the data model classes.
+
+module LaunchDarkly
+  module Impl
+    module Model
+      class Segment
+        # @param data [Hash]
+        # @param logger [Logger|nil]
+        def initialize(data, logger = nil)
+          raise ArgumentError, "expected hash but got #{data.class}" unless data.is_a?(Hash)
+          errors = []
+          @data = data
+          @key = data[:key]
+          @version = data[:version]
+          @deleted = !!data[:deleted]
+          return if @deleted
+          @included = data[:included] || []
+          @excluded = data[:excluded] || []
+          @included_contexts = (data[:includedContexts] || []).map do |target_data|
+            SegmentTarget.new(target_data)
+          end
+          @excluded_contexts = (data[:excludedContexts] || []).map do |target_data|
+            SegmentTarget.new(target_data)
+          end
+          @rules = (data[:rules] || []).map do |rule_data|
+            SegmentRule.new(rule_data, errors)
+          end
+          @unbounded = !!data[:unbounded]
+          @unbounded_context_kind = data[:unboundedContextKind] || LDContext::KIND_DEFAULT
+          @generation = data[:generation]
+          @salt = data[:salt]
+          unless logger.nil?
+            errors.each do |message|
+              logger.error("[LDClient] Data inconsistency in segment \"#{@key}\": #{message}")
+            end
+          end
+        end
+
+        # @return [Hash]
+        attr_reader :data
+        # @return [String]
+        attr_reader :key
+        # @return [Integer]
+        attr_reader :version
+        # @return [Boolean]
+        attr_reader :deleted
+        # @return [Array<String>]
+        attr_reader :included
+        # @return [Array<String>]
+        attr_reader :excluded
+        # @return [Array<LaunchDarkly::Impl::Model::SegmentTarget>]
+        attr_reader :included_contexts
+        # @return [Array<LaunchDarkly::Impl::Model::SegmentTarget>]
+        attr_reader :excluded_contexts
+        # @return [Array<SegmentRule>]
+        attr_reader :rules
+        # @return [Boolean]
+        attr_reader :unbounded
+        # @return [String]
+        attr_reader :unbounded_context_kind
+        # @return [Integer|nil]
+        attr_reader :generation
+        # @return [String]
+        attr_reader :salt
+
+        # This method allows us to read properties of the object as if it's just a hash. Currently this is
+        # necessary because some data store logic is still written to expect hashes; we can remove it once
+        # we migrate entirely to using attributes of the class.
+        def [](key)
+          @data[key]
+        end
+
+        def ==(other)
+          other.is_a?(Segment) && other.data == self.data
+        end
+
+        def as_json(*) # parameter is unused, but may be passed if we're using the json gem
+          @data
+        end
+
+        # Same as as_json, but converts the JSON structure into a string.
+        def to_json(*a)
+          as_json.to_json(*a)
+        end
+      end
+
+      class SegmentTarget
+        def initialize(data)
+          @data = data
+          @context_kind = data[:contextKind]
+          @values = Set.new(data[:values] || [])
+        end
+
+        # @return [Hash]
+        attr_reader :data
+        # @return [String]
+        attr_reader :context_kind
+        # @return [Set]
+        attr_reader :values
+      end
+
+      class SegmentRule
+        def initialize(data, errors_out = nil)
+          @data = data
+          @clauses = (data[:clauses] || []).map do |clause_data|
+            Clause.new(clause_data, errors_out)
+          end
+          @weight = data[:weight]
+          @bucket_by = data[:bucketBy]
+          @rollout_context_kind = data[:rolloutContextKind]
+        end
+
+        # @return [Hash]
+        attr_reader :data
+        # @return [Array<LaunchDarkly::Impl::Model::Clause>]
+        attr_reader :clauses
+        # @return [Integer|nil]
+        attr_reader :weight
+        # @return [String|nil]
+        attr_reader :bucket_by
+        # @return [String|nil]
+        attr_reader :rollout_context_kind
+      end
+
+      # Clause is defined in its own file because clauses are used by both flags and segments
+    end
+  end
+end

data/lib/ldclient-rb/impl/model/serialization.rb

@@ -1,61 +1,71 @@
+require "ldclient-rb/impl/model/feature_flag"
+require "ldclient-rb/impl/model/preprocessed_data"
+require "ldclient-rb/impl/model/segment"
+
+# General implementation notes about the data model classes in LaunchDarkly::Impl::Model--
+#
+# As soon as we receive flag/segment JSON data from LaunchDarkly (or, read it from a database), we
+# transform it into the model classes FeatureFlag, Segment, etc. The constructor of each of these
+# classes takes a hash (the parsed JSON), and transforms it into an internal representation that
+# is more efficient for evaluations.
+#
+# Validation works as follows:
+# - A property value that is of the correct type, but is invalid for other reasons (for example,
+# if a flag rule refers to variation index 5, but there are only 2 variations in the flag), does
+# not prevent the flag from being parsed and stored. It does cause a warning to be logged, if a
+# logger was passed to the constructor.
+# - If a value is completely invalid for the schema, the constructor may throw an
+# exception, causing the whole data set to be rejected. This is consistent with the behavior of
+# the strongly-typed SDKs.
+#
+# Currently, the model classes also retain the original hash of the parsed JSON. This is because
+# we may need to re-serialize them to JSON, and building the JSON on the fly would be very
+# inefficient, so each model class has a to_json method that just returns the same Hash. If we
+# are able in the future to either use a custom streaming serializer, or pass the JSON data
+# straight through from LaunchDarkly to a database instead of re-serializing, we could stop
+# retaining this data.
 
 module LaunchDarkly
   module Impl
     module Model
       # Abstraction of deserializing a feature flag or segment that was read from a data store or
       # received from LaunchDarkly.
-      def self.deserialize(kind, json)
-        return nil if json.nil?
-        item = JSON.parse(json, symbolize_names: true)
-        postprocess_item_after_deserializing!(kind, item)
-        item
+      #
+      # SDK code outside of Impl::Model should use this method instead of calling the model class
+      # constructors directly, so as not to rely on implementation details.
+      #
+      # @param kind [Hash] normally either FEATURES or SEGMENTS
+      # @param input [object] a JSON string or a parsed hash (or a data model object, in which case
+      #  we'll just return the original object)
+      # @param logger [Logger|nil] logs errors if there are any data validation problems
+      # @return [Object] the flag or segment (or, for an unknown data kind, the data as a hash)
+      def self.deserialize(kind, input, logger = nil)
+        return nil if input.nil?
+        return input if !input.is_a?(String) && !input.is_a?(Hash)
+        data = input.is_a?(Hash) ? input : JSON.parse(input, symbolize_names: true)
+        case kind
+        when FEATURES
+          FeatureFlag.new(data, logger)
+        when SEGMENTS
+          Segment.new(data, logger)
+        else
+          data
+        end
       end
 
       # Abstraction of serializing a feature flag or segment that will be written to a data store.
-      # Currently we just call to_json.
+      # Currently we just call to_json, but SDK code outside of Impl::Model should use this method
+      # instead of to_json, so as not to rely on implementation details.
       def self.serialize(kind, item)
         item.to_json
       end
 
       # Translates a { flags: ..., segments: ... } object received from LaunchDarkly to the data store format.
-      def self.make_all_store_data(received_data)
-        flags = received_data[:flags]
-        postprocess_items_after_deserializing!(FEATURES, flags)
-        segments = received_data[:segments]
-        postprocess_items_after_deserializing!(SEGMENTS, segments)
-        { FEATURES => flags, SEGMENTS => segments }
-      end
-
-      # Called after we have deserialized a model item from JSON (because we received it from LaunchDarkly,
-      # or read it from a persistent data store). This allows us to precompute some derived attributes that
-      # will never change during the lifetime of that item.
-      def self.postprocess_item_after_deserializing!(kind, item)
-        return if !item
-        # Currently we are special-casing this for FEATURES; eventually it will be handled by delegating
-        # to the "kind" object or the item class.
-        if kind.eql? FEATURES
-          # For feature flags, we precompute all possible parameterized EvaluationReason instances.
-          prereqs = item[:prerequisites]
-          if !prereqs.nil?
-            prereqs.each do |prereq|
-              prereq[:_reason] = EvaluationReason::prerequisite_failed(prereq[:key])
-            end
-          end
-          rules = item[:rules]
-          if !rules.nil?
-            rules.each_index do |i|
-              rule = rules[i]
-              rule[:_reason] = EvaluationReason::rule_match(i, rule[:id])
-            end
-          end
-        end
-      end
-
-      def self.postprocess_items_after_deserializing!(kind, items_map)
-        return items_map if !items_map
-        items_map.each do |key, item|
-          postprocess_item_after_deserializing!(kind, item)
-        end
+      def self.make_all_store_data(received_data, logger = nil)
+        {
+          FEATURES => (received_data[:flags] || {}).transform_values { |data| FeatureFlag.new(data, logger) },
+          SEGMENTS => (received_data[:segments] || {}).transform_values { |data| Segment.new(data, logger) },
+        }
       end
     end
   end

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

@@ -16,10 +16,9 @@ module LaunchDarkly
 
       def start
         @worker = Thread.new do
-          if @start_delay
-            sleep(@start_delay)
-          end
-          while !@stopped.value do
+          sleep(@start_delay) unless @start_delay.nil? || @start_delay == 0
+
+          until @stopped.value do
             started_at = Time.now
             begin
               @task.call

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

@@ -0,0 +1,25 @@
+module LaunchDarkly
+  module Impl
+    class Sampler
+      #
+      # @param random [Random]
+      #
+      def initialize(random)
+        @random = random
+      end
+
+      #
+      # @param ratio [Int]
+      #
+      # @return [Boolean]
+      #
+      def sample(ratio)
+        return false unless ratio.is_a? Integer
+        return false if ratio <= 0
+        return true if ratio == 1
+
+        @random.rand(1.0) < 1.0 / ratio
+      end
+    end
+  end
+end