launchdarkly-server-sdk 6.3.0 → 8.0.0

data/lib/ldclient-rb/integrations/test_data/flag_builder.rb

@@ -43,9 +43,50 @@ module LaunchDarkly
           self
         end
 
+        #
+        # Set the migration related settings for this feature flag.
+        #
+        # The settings hash should be built using the {FlagMigrationSettingsBuilder}.
+        #
+        # @param settings [Hash]
+        # @return [FlagBuilder] the builder
+        #
+        def migration_settings(settings)
+          @migration_settings = settings
+          self
+        end
+
+        #
+        # Set the sampling ratio for this flag. This ratio is used to control the emission rate of feature, debug, and
+        # migration op events.
+        #
+        # General usage should not require interacting with this method.
+        #
+        # @param ratio [Integer]
+        # @return [FlagBuilder]
+        #
+        def sampling_ratio(ratio)
+          @sampling_ratio = ratio
+          self
+        end
+
+        #
+        # Set the option to exclude this flag from summary events. This is used to control the size of the summary event
+        # in the event certain flag payloads are large.
+        #
+        # General usage should not require interacting with this method.
+        #
+        # @param exclude [Boolean]
+        # @return [FlagBuilder]
+        #
+        def exclude_from_summaries(exclude)
+          @exclude_from_summaries = exclude
+          self
+        end
+
         #
         # Specifies the fallthrough variation. The fallthrough is the value
-        # that is returned if targeting is on and the user was not matched by a more specific
+        # that is returned if targeting is on and the context was not matched by a more specific
         # target or rule.
         #
         # If the flag was previously configured with other variations and the variation specified is a boolean,
@@ -56,7 +97,7 @@ module LaunchDarkly
         # @return [FlagBuilder] the builder
         #
         def fallthrough_variation(variation)
-          if LaunchDarkly::Impl::Util.is_bool variation then
+          if LaunchDarkly::Impl::Util.bool? variation
             boolean_flag.fallthrough_variation(variation_for_boolean(variation))
           else
             @fallthrough_variation = variation
@@ -76,7 +117,7 @@ module LaunchDarkly
         # @return [FlagBuilder] the builder
         #
         def off_variation(variation)
-          if LaunchDarkly::Impl::Util.is_bool variation then
+          if LaunchDarkly::Impl::Util.bool? variation
             boolean_flag.off_variation(variation_for_boolean(variation))
           else
             @off_variation = variation
@@ -108,7 +149,7 @@ module LaunchDarkly
         end
 
         #
-        # Sets the flag to always return the specified variation for all users.
+        # Sets the flag to always return the specified variation for all contexts.
         #
         # The variation is specified, Targeting is switched on, and any existing targets or rules are removed.
         # The fallthrough variation is set to the specified value. The off variation is left unchanged.
@@ -120,31 +161,31 @@ module LaunchDarkly
         #                  0 for the first, 1 for the second, etc.
         # @return [FlagBuilder] the builder
         #
-        def variation_for_all_users(variation)
-          if LaunchDarkly::Impl::Util.is_bool variation then
-            boolean_flag.variation_for_all_users(variation_for_boolean(variation))
+        def variation_for_all(variation)
+          if LaunchDarkly::Impl::Util.bool? variation
+            boolean_flag.variation_for_all(variation_for_boolean(variation))
           else
-            on(true).clear_rules.clear_user_targets.fallthrough_variation(variation)
+            on(true).clear_rules.clear_targets.fallthrough_variation(variation)
           end
         end
 
         #
-        # Sets the flag to always return the specified variation value for all users.
+        # Sets the flag to always return the specified variation value for all context.
         #
         # The value may be of any valid JSON type. This method changes the
         # flag to have only a single variation, which is this value, and to return the same
         # variation regardless of whether targeting is on or off. Any existing targets or rules
         # are removed.
         #
-        # @param value [Object] the desired value to be returned for all users
+        # @param value [Object] the desired value to be returned for all contexts
         # @return [FlagBuilder] the builder
         #
-        def value_for_all_users(value)
-          variations(value).variation_for_all_users(0)
+        def value_for_all(value)
+          variations(value).variation_for_all(0)
         end
 
         #
-        # Sets the flag to return the specified variation for a specific user key when targeting
+        # Sets the flag to return the specified variation for a specific context key when targeting
         # is on.
         #
         # This has no effect when targeting is turned off for the flag.
@@ -152,36 +193,87 @@ module LaunchDarkly
         # If the flag was previously configured with other variations and the variation specified is a boolean,
         # this also changes it to a boolean flag.
         #
-        # @param user_key [String] a user key
+        # @param context_kind [String] a context kind
+        # @param context_key [String] a context key
         # @param variation [Boolean, Integer] true or false or the desired variation index to return:
         #                  0 for the first, 1 for the second, etc.
         # @return [FlagBuilder] the builder
         #
-        def variation_for_user(user_key, variation)
-          if LaunchDarkly::Impl::Util.is_bool variation then
-            boolean_flag.variation_for_user(user_key, variation_for_boolean(variation))
-          else
-            if @targets.nil? then
-              @targets = Hash.new
-            end
-            @variations.count.times do | i |
-              if i == variation then
-                if @targets[i].nil? then
-                  @targets[i] = [user_key]
-                else
-                  @targets[i].push(user_key)
-                end
-              elsif not @targets[i].nil? then
-                @targets[i].delete(user_key)
+        def variation_for_key(context_kind, context_key, variation)
+          if LaunchDarkly::Impl::Util.bool? variation
+            return boolean_flag.variation_for_key(context_kind, context_key, variation_for_boolean(variation))
+          end
+
+          if @targets.nil?
+            @targets = Hash.new
+          end
+
+          targets = @targets[context_kind] || []
+          @variations.count.times do | i |
+            if i == variation
+              if targets[i].nil?
+                targets[i] = [context_key]
+              else
+                targets[i].push(context_key)
               end
+            elsif not targets[i].nil?
+              targets[i].delete(context_key)
             end
-            self
           end
+
+          @targets[context_kind] = targets
+
+          self
+        end
+
+        #
+        # Sets the flag to return the specified variation for a specific user key when targeting
+        # is on.
+        #
+        # This is a shortcut for calling {variation_for_key} with
+        # `LaunchDarkly::LDContext::KIND_DEFAULT` as the context kind.
+        #
+        # This has no effect when targeting is turned off for the flag.
+        #
+        # If the flag was previously configured with other variations and the variation specified is a boolean,
+        # this also changes it to a boolean flag.
+        #
+        # @param user_key [String] a user key
+        # @param variation [Boolean, Integer] true or false or the desired variation index to return:
+        #                  0 for the first, 1 for the second, etc.
+        # @return [FlagBuilder] the builder
+        #
+        def variation_for_user(user_key, variation)
+          variation_for_key(LaunchDarkly::LDContext::KIND_DEFAULT, user_key, variation)
+        end
+
+        #
+        # Starts defining a flag rule, using the "is one of" operator.
+        #
+        # @example create a rule that returns `true` if the name is "Patsy" or "Edina" and the context kind is "user"
+        #     testData.flag("flag")
+        #         .if_match_context("user", :name, 'Patsy', 'Edina')
+        #         .then_return(true);
+        #
+        # @param context_kind [String] a context kind
+        # @param attribute [Symbol] the context attribute to match against
+        # @param values [Array<Object>] values to compare to
+        # @return [FlagRuleBuilder] a flag rule builder
+        #
+        # @see FlagRuleBuilder#then_return
+        # @see FlagRuleBuilder#and_match
+        # @see FlagRuleBuilder#and_not_match
+        #
+        def if_match_context(context_kind, attribute, *values)
+          FlagRuleBuilder.new(self).and_match_context(context_kind, attribute, *values)
         end
 
         #
         # Starts defining a flag rule, using the "is one of" operator.
         #
+        # This is a shortcut for calling {if_match_context} with
+        # `LaunchDarkly::LDContext::KIND_DEFAULT` as the context kind.
+        #
         # @example create a rule that returns `true` if the name is "Patsy" or "Edina"
         #     testData.flag("flag")
         #         .if_match(:name, 'Patsy', 'Edina')
@@ -196,7 +288,7 @@ module LaunchDarkly
         # @see FlagRuleBuilder#and_not_match
         #
         def if_match(attribute, *values)
-          FlagRuleBuilder.new(self).and_match(attribute, *values)
+          if_match_context(LaunchDarkly::LDContext::KIND_DEFAULT, attribute, *values)
         end
 
         #
@@ -204,6 +296,30 @@ module LaunchDarkly
         #
         # @example create a rule that returns `true` if the name is neither "Saffron" nor "Bubble"
         #     testData.flag("flag")
+        #         .if_not_match_context("user", :name, 'Saffron', 'Bubble')
+        #         .then_return(true)
+        #
+        # @param context_kind [String] a context kind
+        # @param attribute [Symbol] the context attribute to match against
+        # @param values [Array<Object>] values to compare to
+        # @return [FlagRuleBuilder] a flag rule builder
+        #
+        # @see FlagRuleBuilder#then_return
+        # @see FlagRuleBuilder#and_match
+        # @see FlagRuleBuilder#and_not_match
+        #
+        def if_not_match_context(context_kind, attribute, *values)
+          FlagRuleBuilder.new(self).and_not_match_context(context_kind, attribute, *values)
+        end
+
+        #
+        # Starts defining a flag rule, using the "is not one of" operator.
+        #
+        # This is a shortcut for calling {if_not_match_context} with
+        # `LaunchDarkly::LDContext::KIND_DEFAULT` as the context kind.
+        #
+        # @example create a rule that returns `true` if the name is neither "Saffron" nor "Bubble"
+        #     testData.flag("flag")
         #         .if_not_match(:name, 'Saffron', 'Bubble')
         #         .then_return(true)
         #
@@ -216,16 +332,16 @@ module LaunchDarkly
         # @see FlagRuleBuilder#and_not_match
         #
         def if_not_match(attribute, *values)
-          FlagRuleBuilder.new(self).and_not_match(attribute, *values)
+          if_not_match_context(LaunchDarkly::LDContext::KIND_DEFAULT, attribute, *values)
         end
 
         #
-        # Removes any existing user targets from the flag.
-        # This undoes the effect of methods like {#variation_for_user}
+        # Removes any existing targets from the flag.
+        # This undoes the effect of methods like {#variation_for_key}
         #
         # @return [FlagBuilder] the same builder
         #
-        def clear_user_targets
+        def clear_targets
           @targets = nil
           self
         end
@@ -243,7 +359,7 @@ module LaunchDarkly
 
         # @private
         def add_rule(rule)
-          if @rules.nil? then
+          if @rules.nil?
             @rules = Array.new
           end
           @rules.push(rule)
@@ -261,7 +377,7 @@ module LaunchDarkly
         # @return [FlagBuilder] the builder
         #
         def boolean_flag
-          if is_boolean_flag then
+          if boolean_flag?
             self
           else
             variations(true, false)
@@ -278,33 +394,90 @@ module LaunchDarkly
                   variations: @variations,
                 }
 
-          unless @off_variation.nil? then
+          unless @off_variation.nil?
             res[:offVariation] = @off_variation
           end
 
-          unless @fallthrough_variation.nil? then
+          unless @fallthrough_variation.nil?
             res[:fallthrough] = { variation: @fallthrough_variation }
           end
 
-          unless @targets.nil? then
-            res[:targets] = @targets.collect do | variation, values |
-              { variation: variation, values: values }
+          unless @migration_settings.nil?
+            res[:migration] = @migration_settings
+          end
+
+          unless @sampling_ratio.nil? || @sampling_ratio == 1
+            res[:samplingRatio] = @sampling_ratio
+          end
+
+          unless @exclude_from_summaries.nil? || !@exclude_from_summaries
+            res[:excludeFromSummaries] = @exclude_from_summaries
+          end
+
+          unless @targets.nil?
+            targets = []
+            context_targets = []
+
+            @targets.each do |kind, targets_for_kind|
+              targets_for_kind.each_with_index do |values, variation|
+                next if values.nil?
+                if kind == LaunchDarkly::LDContext::KIND_DEFAULT
+                  targets << { variation: variation, values: values }
+                  context_targets << { contextKind: LaunchDarkly::LDContext::KIND_DEFAULT, variation: variation, values: [] }
+                else
+                  context_targets << { contextKind: kind, variation: variation, values: values }
+                end
+              end
             end
+
+            res[:targets] = targets
+            res[:contextTargets] = context_targets
           end
 
-          unless @rules.nil? then
-            res[:rules] = @rules.each_with_index.collect { | rule, i | rule.build(i) }
+          unless @rules.nil?
+            res[:rules] = @rules.each_with_index.map { | rule, i | rule.build(i) }
           end
 
           res
         end
 
+        #
+        # A builder for feature flag migration settings to be used with {FlagBuilder}.
+        #
+        # In the LaunchDarkly model, a flag can be a standard feature flag, or it can be a migration-related flag, in
+        # which case it has migration-specified related settings. These settings control things like the rate at which
+        # reads are tested for consistency between origins.
+        #
+        class FlagMigrationSettingsBuilder
+          def initialize()
+            @check_ratio = nil
+          end
+
+          #
+          # @param ratio [Integer]
+          # @return [FlagMigrationSettingsBuilder]
+          #
+          def check_ratio(ratio)
+            return unless ratio.is_a? Integer
+            @check_ratio = ratio
+            self
+          end
+
+          def build
+            return nil if @check_ratio.nil? || @check_ratio == 1
+
+            {
+              "checkRatio": @check_ratio,
+            }
+          end
+        end
+
         #
         # A builder for feature flag rules to be used with {FlagBuilder}.
         #
         # In the LaunchDarkly model, a flag can have any number of rules, and a rule can have any number of
-        # clauses. A clause is an individual test such as "name is 'X'". A rule matches a user if all of the
-        # rule's clauses match the user.
+        # clauses. A clause is an individual test such as "name is 'X'". A rule matches a context if all of the
+        # rule's clauses match the context.
         #
         # To start defining a rule, use one of the flag builder's matching methods such as
         # {FlagBuilder#if_match}. This defines the first clause for the rule.
@@ -314,7 +487,7 @@ module LaunchDarkly
         #
         class FlagRuleBuilder
           # @private
-          FlagRuleClause = Struct.new(:attribute, :op, :values, :negate, keyword_init: true)
+          FlagRuleClause = Struct.new(:contextKind, :attribute, :op, :values, :negate, keyword_init: true)
 
           # @private
           def initialize(flag_builder)
@@ -331,6 +504,34 @@ module LaunchDarkly
           #
           # Adds another clause, using the "is one of" operator.
           #
+          # @example create a rule that returns `true` if the name is "Patsy", the country is "gb", and the context kind is "user"
+          #     testData.flag("flag")
+          #         .if_match_context("user", :name, 'Patsy')
+          #         .and_match_context("user", :country, 'gb')
+          #         .then_return(true)
+          #
+          # @param context_kind [String] a context kind
+          # @param attribute [Symbol] the context attribute to match against
+          # @param values [Array<Object>] values to compare to
+          # @return [FlagRuleBuilder] the rule builder
+          #
+          def and_match_context(context_kind, attribute, *values)
+            @clauses.push(FlagRuleClause.new(
+              contextKind: context_kind,
+              attribute: attribute,
+              op: 'in',
+              values: values,
+              negate: false
+            ))
+            self
+          end
+
+          #
+          # Adds another clause, using the "is one of" operator.
+          #
+          # This is a shortcut for calling {and_match_context} with
+          # `LaunchDarkly::LDContext::KIND_DEFAULT` as the context kind.
+          #
           # @example create a rule that returns `true` if the name is "Patsy" and the country is "gb"
           #     testData.flag("flag")
           #         .if_match(:name, 'Patsy')
@@ -342,11 +543,30 @@ module LaunchDarkly
           # @return [FlagRuleBuilder] the rule builder
           #
           def and_match(attribute, *values)
+            and_match_context(LaunchDarkly::LDContext::KIND_DEFAULT, attribute, *values)
+          end
+
+          #
+          # Adds another clause, using the "is not one of" operator.
+          #
+          # @example create a rule that returns `true` if the name is "Patsy" and the country is not "gb"
+          #     testData.flag("flag")
+          #         .if_match_context("user", :name, 'Patsy')
+          #         .and_not_match_context("user", :country, 'gb')
+          #         .then_return(true)
+          #
+          # @param context_kind [String] a context kind
+          # @param attribute [Symbol] the context attribute to match against
+          # @param values [Array<Object>] values to compare to
+          # @return [FlagRuleBuilder] the rule builder
+          #
+          def and_not_match_context(context_kind, attribute, *values)
             @clauses.push(FlagRuleClause.new(
+              contextKind: context_kind,
               attribute: attribute,
               op: 'in',
               values: values,
-              negate: false
+              negate: true
             ))
             self
           end
@@ -354,6 +574,9 @@ module LaunchDarkly
           #
           # Adds another clause, using the "is not one of" operator.
           #
+          # This is a shortcut for calling {and_not_match} with
+          # `LaunchDarkly::LDContext::KIND_DEFAULT` as the context kind.
+          #
           # @example create a rule that returns `true` if the name is "Patsy" and the country is not "gb"
           #     testData.flag("flag")
           #         .if_match(:name, 'Patsy')
@@ -365,13 +588,7 @@ module LaunchDarkly
           # @return [FlagRuleBuilder] the rule builder
           #
           def and_not_match(attribute, *values)
-            @clauses.push(FlagRuleClause.new(
-              attribute: attribute,
-              op: 'in',
-              values: values,
-              negate: true
-            ))
-            self
+            and_not_match_context(LaunchDarkly::LDContext::KIND_DEFAULT, attribute, *values)
           end
 
           #
@@ -386,7 +603,7 @@ module LaunchDarkly
           # @return [FlagBuilder] the flag builder with this rule added
           #
           def then_return(variation)
-            if LaunchDarkly::Impl::Util.is_bool variation then
+            if LaunchDarkly::Impl::Util.bool? variation
               @variation = @flag_builder.variation_for_boolean(variation)
               @flag_builder.boolean_flag.add_rule(self)
             else
@@ -400,7 +617,7 @@ module LaunchDarkly
             {
               id: 'rule' + ri.to_s,
               variation: @variation,
-              clauses: @clauses.collect(&:to_h)
+              clauses: @clauses.map(&:to_h),
             }
           end
         end
@@ -415,15 +632,23 @@ module LaunchDarkly
         TRUE_VARIATION_INDEX = 0
         FALSE_VARIATION_INDEX = 1
 
-        def is_boolean_flag
+        def boolean_flag?
           @variations.size == 2 &&
-          @variations[TRUE_VARIATION_INDEX] == true &&
-          @variations[FALSE_VARIATION_INDEX] == false
+            @variations[TRUE_VARIATION_INDEX] == true &&
+            @variations[FALSE_VARIATION_INDEX] == false
         end
 
         def deep_copy_hash(from)
           to = Hash.new
-          from.each { |k, v| to[k] = v.clone }
+          from.each do |k, v|
+            if v.is_a?(Hash)
+              to[k] = deep_copy_hash(v)
+            elsif v.is_a?(Array)
+              to[k] = deep_copy_array(v)
+            else
+              to[k] = v.clone
+            end
+          end
           to
         end
 

data/lib/ldclient-rb/integrations/test_data.rb

@@ -1,4 +1,6 @@
 require 'ldclient-rb/impl/integrations/test_data/test_data_source'
+require 'ldclient-rb/impl/model/feature_flag'
+require 'ldclient-rb/impl/model/segment'
 require 'ldclient-rb/integrations/test_data/flag_builder'
 
 require 'concurrent/atomics'
@@ -14,12 +16,12 @@ module LaunchDarkly
     #
     # @example
     #     td = LaunchDarkly::Integrations::TestData.data_source
-    #     td.update(td.flag("flag-key-1").variation_for_all_users(true))
+    #     td.update(td.flag("flag-key-1").variation_for_all(true))
     #     config = LaunchDarkly::Config.new(data_source: td)
     #     client = LaunchDarkly::LDClient.new('sdkKey', config)
     #     # flags can be updated at any time:
     #     td.update(td.flag("flag-key-2")
-    #                 .variation_for_user("some-user-key", true)
+    #                 .variation_for_key("user", some-user-key", true)
     #                 .fallthrough_variation(false))
     #
     # The above example uses a simple boolean flag, but more complex configurations are possible using
@@ -77,7 +79,7 @@ module LaunchDarkly
       # starts with the same configuration that was last provided for this flag.
       #
       # Otherwise, it starts with a new default configuration in which the flag has `true` and
-      # `false` variations, is `true` for all users when targeting is turned on and
+      # `false` variations, is `true` for all contexts when targeting is turned on and
       # `false` otherwise, and currently has targeting turned on. You can change any of those
       # properties, and provide more complex behavior, using the {FlagBuilder} methods.
       #
@@ -88,7 +90,7 @@ module LaunchDarkly
       #
       def flag(key)
         existing_builder = @lock.with_read_lock { @flag_builders[key] }
-        if existing_builder.nil? then
+        if existing_builder.nil?
           FlagBuilder.new(key).boolean_flag
         else
           existing_builder.clone
@@ -116,10 +118,10 @@ module LaunchDarkly
           @flag_builders[flag_builder.key] = flag_builder
           version = 0
           flag_key = flag_builder.key.to_sym
-          if @current_flags[flag_key] then
+          if @current_flags[flag_key]
             version = @current_flags[flag_key][:version]
           end
-          new_flag = flag_builder.build(version+1)
+          new_flag = Impl::Model.deserialize(FEATURES, flag_builder.build(version+1))
           @current_flags[flag_key] = new_flag
         end
         update_item(FEATURES, new_flag)
@@ -149,15 +151,15 @@ module LaunchDarkly
       end
 
       #
-      # Copies a full user segment data model object into the test data.
+      # Copies a full segment data model object into the test data.
       #
       # It immediately propagates the change to any `LDClient` instance(s) that you have already
       # configured to use this `TestData`. If no `LDClient` has been started yet, it simply adds
       # this segment to the test data which will be provided to any LDClient that you subsequently
       # configure.
       #
-      # This method is currently the only way to inject user segment data, since there is no builder
-      # API for segments. It is mainly intended for the SDK's own tests of user segment functionality,
+      # This method is currently the only way to inject segment data, since there is no builder
+      # API for segments. It is mainly intended for the SDK's own tests of segment functionality,
       # since application tests that need to produce a desired evaluation state could do so more easily
       # by just setting flag values.
       #
@@ -169,12 +171,14 @@ module LaunchDarkly
       end
 
       private def use_preconfigured_item(kind, item, current)
-        key = item[:key].to_sym
+        item = Impl::Model.deserialize(kind, item)
+        key = item.key.to_sym
         @lock.with_write_lock do
           old_item = current[key]
-          if !old_item.nil? then
-            item = item.clone
-            item[:version] = old_item[:version] + 1
+          unless old_item.nil?
+            data = item.as_json
+            data[:version] = old_item.version + 1
+            item = Impl::Model.deserialize(kind, data)
           end
           current[key] = item
         end
@@ -195,7 +199,7 @@ module LaunchDarkly
         @lock.with_read_lock do
           {
             FEATURES => @current_flags.clone,
-            SEGMENTS => @current_segments.clone
+            SEGMENTS => @current_segments.clone,
           }
         end
       end