launchdarkly-server-sdk 6.3.0 → 8.0.0

data/lib/ldclient-rb/context.rb

@@ -0,0 +1,444 @@
+require 'set'
+require 'ldclient-rb/impl/context'
+require 'ldclient-rb/reference'
+
+module LaunchDarkly
+  # LDContext is a collection of attributes that can be referenced in flag
+  # evaluations and analytics events.
+  #
+  # To create an LDContext of a single kind, such as a user, you may use
+  # {LDContext#create} or {LDContext#with_key}.
+  #
+  # To create an LDContext with multiple kinds, use {LDContext#create_multi}.
+  #
+  # Each factory method will always return an LDContext. However, that
+  # LDContext may be invalid. You can check the validity of the resulting
+  # context, and the associated errors by calling {LDContext#valid?} and
+  # {LDContext#error}
+  class LDContext
+    KIND_DEFAULT = "user"
+    KIND_MULTI = "multi"
+
+    ERR_NOT_HASH = 'context data is not a hash'
+    private_constant :ERR_NOT_HASH
+    ERR_KEY_EMPTY = 'context key must not be null or empty'
+    private_constant :ERR_KEY_EMPTY
+    ERR_KIND_MULTI_NON_CONTEXT_ARRAY = 'context data must be an array of valid LDContexts'
+    private_constant :ERR_KIND_MULTI_NON_CONTEXT_ARRAY
+    ERR_KIND_MULTI_CANNOT_CONTAIN_MULTI = 'multi-kind context cannot contain another multi-kind context'
+    private_constant :ERR_KIND_MULTI_CANNOT_CONTAIN_MULTI
+    ERR_KIND_MULTI_WITH_NO_KINDS = 'multi-context must contain at least one kind'
+    private_constant :ERR_KIND_MULTI_WITH_NO_KINDS
+    ERR_KIND_MULTI_DUPLICATES = 'multi-kind context cannot have same kind more than once'
+    private_constant :ERR_KIND_MULTI_DUPLICATES
+    ERR_CUSTOM_NON_HASH = 'context custom must be a hash'
+    private_constant :ERR_CUSTOM_NON_HASH
+    ERR_PRIVATE_NON_ARRAY = 'context private attributes must be an array'
+
+    # @return [String, nil] Returns the key for this context
+    attr_reader :key
+
+    # @return [String, nil] Returns the fully qualified key for this context
+    attr_reader :fully_qualified_key
+
+    # @return [String, nil] Returns the kind for this context
+    attr_reader :kind
+
+    # @return [String, nil] Returns the error associated with this LDContext if invalid
+    attr_reader :error
+
+    # @return [Array<Reference>] Returns the private attributes associated with this LDContext
+    attr_reader :private_attributes
+
+    #
+    # @private
+    # @param key [String, nil]
+    # @param fully_qualified_key [String, nil]
+    # @param kind [String, nil]
+    # @param name [String, nil]
+    # @param anonymous [Boolean, nil]
+    # @param attributes [Hash, nil]
+    # @param private_attributes [Array<String>, nil]
+    # @param error [String, nil]
+    # @param contexts [Array<LDContext>, nil]
+    #
+    def initialize(key, fully_qualified_key, kind, name = nil, anonymous = nil, attributes = nil, private_attributes = nil, error = nil, contexts = nil)
+      @key = key
+      @fully_qualified_key = fully_qualified_key
+      @kind = kind
+      @name = name
+      @anonymous = anonymous || false
+      @attributes = attributes
+      @private_attributes = []
+      (private_attributes || []).each do |attribute|
+        reference = Reference.create(attribute)
+        @private_attributes << reference if reference.error.nil?
+      end
+      @error = error
+      @contexts = contexts
+      @is_multi = !contexts.nil?
+    end
+    private_class_method :new
+
+    #
+    # @return [Boolean] Is this LDContext a multi-kind context?
+    #
+    def multi_kind?
+      @is_multi
+    end
+
+    #
+    # @return [Boolean] Determine if this LDContext is considered valid
+    #
+    def valid?
+      @error.nil?
+    end
+
+    #
+    # Returns a hash mapping each context's kind to its key.
+    #
+    # @return [Hash<Symbol, String>]
+    #
+    def keys
+      return {} unless valid?
+      return Hash[kind, key] unless multi_kind?
+
+      @contexts.map { |c| [c.kind, c.key] }.to_h
+    end
+
+    #
+    # Returns an array of context kinds.
+    #
+    # @return [Array<String>]
+    #
+    def kinds
+      return [] unless valid?
+      return [kind] unless multi_kind?
+
+      @contexts.map { |c| c.kind }
+    end
+
+    #
+    # Return an array of top level attribute keys (excluding built-in attributes)
+    #
+    # @return [Array<Symbol>]
+    #
+    def get_custom_attribute_names
+      return [] if @attributes.nil?
+
+      @attributes.keys
+    end
+
+    #
+    # get_value looks up the value of any attribute of the Context by name.
+    # This includes only attributes that are addressable in evaluations-- not
+    # metadata such as private attributes.
+    #
+    # For a single-kind context, the attribute name can be any custom attribute.
+    # It can also be one of the built-in ones like "kind", "key", or "name".
+    #
+    # For a multi-kind context, the only supported attribute name is "kind".
+    # Use {#individual_context} to inspect a Context for a particular kind and
+    # then get its attributes.
+    #
+    # This method does not support complex expressions for getting individual
+    # values out of JSON objects or arrays, such as "/address/street". Use
+    # {#get_value_for_reference} for that purpose.
+    #
+    # If the value is found, the return value is the attribute value;
+    # otherwise, it is nil.
+    #
+    # @param attribute [String, Symbol]
+    # @return [any]
+    #
+    def get_value(attribute)
+      reference = Reference.create_literal(attribute)
+      get_value_for_reference(reference)
+    end
+
+    #
+    # get_value_for_reference looks up the value of any attribute of the
+    # Context, or a value contained within an attribute, based on a {Reference}
+    # instance. This includes only attributes that are addressable in
+    # evaluations-- not metadata such as private attributes.
+    #
+    # This implements the same behavior that the SDK uses to resolve attribute
+    # references during a flag evaluation. In a single-kind context, the
+    # {Reference} can represent a simple attribute name-- either a built-in one
+    # like "name" or "key", or a custom attribute -- or, it can be a
+    # slash-delimited path using a JSON-Pointer-like syntax. See {Reference}
+    # for more details.
+    #
+    # For a multi-kind context, the only supported attribute name is "kind".
+    # Use {#individual_context} to inspect a Context for a particular kind and
+    # then get its attributes.
+    #
+    # If the value is found, the return value is the attribute value;
+    # otherwise, it is nil.
+    #
+    # @param reference [Reference]
+    # @return [any]
+    #
+    def get_value_for_reference(reference)
+      return nil unless valid?
+      return nil unless reference.is_a?(Reference)
+      return nil unless reference.error.nil?
+
+      first_component = reference.component(0)
+      return nil if first_component.nil?
+
+      if multi_kind?
+        if reference.depth == 1 && first_component == :kind
+          return kind
+        end
+
+        # Multi-kind contexts have no other addressable attributes
+        return nil
+      end
+
+      value = get_top_level_addressable_attribute_single_kind(first_component)
+      return nil if value.nil?
+
+      (1...reference.depth).each do |i|
+        name = reference.component(i)
+
+        return nil unless value.is_a?(Hash)
+        return nil unless value.has_key?(name)
+
+        value = value[name]
+      end
+
+      value
+    end
+
+    #
+    # Returns the number of context kinds in this context.
+    #
+    # For a valid individual context, this returns 1. For a multi-context, it
+    # returns the number of context kinds. For an invalid context, it returns
+    # zero.
+    #
+    # @return [Integer] the number of context kinds
+    #
+    def individual_context_count
+      return 0 unless valid?
+      return 1 if @contexts.nil?
+      @contexts.count
+    end
+
+    #
+    # Returns the single-kind LDContext corresponding to one of the kinds in
+    # this context.
+    #
+    # The `kind` parameter can be either a number representing a zero-based
+    # index, or a string representing a context kind.
+    #
+    # If this method is called on a single-kind LDContext, then the only
+    # allowable value for `kind` is either zero or the same value as {#kind},
+    # and the return value on success is the same LDContext.
+    #
+    # If the method is called on a multi-context, and `kind` is a number, it
+    # must be a non-negative index that is less than the number of kinds (that
+    # is, less than the return value of {#individual_context_count}, and the
+    # return value on success is one of the individual LDContexts within. Or,
+    # if `kind` is a string, it must match the context kind of one of the
+    # individual contexts.
+    #
+    # If there is no context corresponding to `kind`, the method returns nil.
+    #
+    # @param kind [Integer, String] the index or string value of a context kind
+    # @return [LDContext, nil] the context corresponding to that index or kind,
+    #   or null if none.
+    #
+    def individual_context(kind)
+      return nil unless valid?
+
+      if kind.is_a?(Integer)
+        unless multi_kind?
+          return kind == 0 ? self : nil
+        end
+
+        return kind >= 0 && kind < @contexts.count ? @contexts[kind] : nil
+      end
+
+      return nil unless kind.is_a?(String)
+
+      unless multi_kind?
+        return self.kind == kind ? self : nil
+      end
+
+      @contexts.each do |context|
+        return context if context.kind == kind
+      end
+
+      nil
+    end
+
+    #
+    # Retrieve the value of any top level, addressable attribute.
+    #
+    # This method returns an array of two values. The first element is the
+    # value of the requested attribute or nil if it does not exist. The second
+    # value will be true if the attribute exists; otherwise, it will be false.
+    #
+    # @param name [Symbol]
+    # @return [any]
+    #
+    private def get_top_level_addressable_attribute_single_kind(name)
+      case name
+      when :kind
+        kind
+      when :key
+        key
+      when :name
+        @name
+      when :anonymous
+        @anonymous
+      else
+        @attributes&.fetch(name, nil)
+      end
+    end
+
+    #
+    # Convenience method to create a simple single kind context providing only
+    # a key and kind type.
+    #
+    # @param key [String]
+    # @param kind [String]
+    #
+    def self.with_key(key, kind = KIND_DEFAULT)
+      create({key: key, kind: kind})
+    end
+
+    #
+    # Create a single kind context from the provided hash.
+    #
+    # The provided hash must match the format as outlined in the
+    # {https://docs.launchdarkly.com/sdk/features/user-config SDK
+    # documentation}.
+    #
+    # @deprecated The old user format will be removed in 8.0.0. Please use the new context specific format.
+    #
+    # @param data [Hash]
+    # @return [LDContext]
+    #
+    def self.create(data)
+      return create_invalid_context(ERR_NOT_HASH) unless data.is_a?(Hash)
+
+      kind = data[:kind]
+      if kind == KIND_MULTI
+        contexts = []
+        data.each do |key, value|
+          next if key == :kind
+          contexts << create_single_context(value, key.to_s)
+        end
+
+        return create_multi(contexts)
+      end
+
+      create_single_context(data, kind)
+    end
+
+    #
+    # Create a multi-kind context from the array of LDContexts provided.
+    #
+    # A multi-kind context is comprised of two or more single kind contexts.
+    # You cannot include a multi-kind context instead another multi-kind
+    # context.
+    #
+    # Additionally, the kind of each single-kind context must be unique. For
+    # instance, you cannot create a multi-kind context that includes two user
+    # kind contexts.
+    #
+    # If you attempt to create a multi-kind context from one single-kind
+    # context, this method will return the single-kind context instead of a new
+    # multi-kind context wrapping that one single-kind.
+    #
+    # @param contexts [Array<LDContext>]
+    # @return [LDContext]
+    #
+    def self.create_multi(contexts)
+      return create_invalid_context(ERR_KIND_MULTI_NON_CONTEXT_ARRAY) unless contexts.is_a?(Array)
+      return create_invalid_context(ERR_KIND_MULTI_WITH_NO_KINDS) if contexts.empty?
+
+      kinds = Set.new
+      contexts.each do |context|
+        if !context.is_a?(LDContext)
+          return create_invalid_context(ERR_KIND_MULTI_NON_CONTEXT_ARRAY)
+        elsif !context.valid?
+          return create_invalid_context(ERR_KIND_MULTI_NON_CONTEXT_ARRAY)
+        elsif context.multi_kind?
+          return create_invalid_context(ERR_KIND_MULTI_CANNOT_CONTAIN_MULTI)
+        elsif kinds.include? context.kind
+          return create_invalid_context(ERR_KIND_MULTI_DUPLICATES)
+        end
+
+        kinds.add(context.kind)
+      end
+
+      return contexts[0] if contexts.length == 1
+
+      full_key = contexts.sort_by(&:kind)
+                         .map { |c| LaunchDarkly::Impl::Context::canonicalize_key_for_kind(c.kind, c.key) }
+                         .join(":")
+
+      new(nil, full_key, "multi", nil, false, nil, nil, nil, contexts)
+    end
+
+    #
+    # @param error [String]
+    # @return [LDContext]
+    #
+    private_class_method def self.create_invalid_context(error)
+      new(nil, nil, nil, nil, false, nil, nil, error)
+    end
+
+    #
+    # @param data [Hash]
+    # @param kind [String]
+    # @return [LaunchDarkly::LDContext]
+    #
+    private_class_method def self.create_single_context(data, kind)
+      unless data.is_a?(Hash)
+        return create_invalid_context(ERR_NOT_HASH)
+      end
+
+      kind_error = LaunchDarkly::Impl::Context.validate_kind(kind)
+      return create_invalid_context(kind_error) unless kind_error.nil?
+
+      key = data[:key]
+      key_error = LaunchDarkly::Impl::Context.validate_key(key)
+      return create_invalid_context(key_error) unless key_error.nil?
+
+      name = data[:name]
+      name_error = LaunchDarkly::Impl::Context.validate_name(name)
+      return create_invalid_context(name_error) unless name_error.nil?
+
+      anonymous = data.fetch(:anonymous, false)
+      anonymous_error = LaunchDarkly::Impl::Context.validate_anonymous(anonymous, false)
+      return create_invalid_context(anonymous_error) unless anonymous_error.nil?
+
+      meta = data.fetch(:_meta, {})
+      private_attributes = meta[:privateAttributes]
+      if private_attributes && !private_attributes.is_a?(Array)
+        return create_invalid_context(ERR_PRIVATE_NON_ARRAY)
+      end
+
+      # We only need to create an attribute hash if there are keys set outside
+      # of the ones we store in dedicated instance variables.
+      attributes = nil
+      data.each do |k, v|
+        case k
+        when :kind, :key, :name, :anonymous, :_meta
+          next
+        else
+          attributes ||= {}
+          attributes[k] = v.clone
+        end
+      end
+
+      full_key = kind == LDContext::KIND_DEFAULT ? key.to_s : LaunchDarkly::Impl::Context::canonicalize_key_for_kind(kind, key.to_s)
+      new(key.to_s, full_key, kind, name, anonymous, attributes, private_attributes)
+    end
+  end
+end

data/lib/ldclient-rb/evaluation_detail.rb

@@ -1,4 +1,3 @@
-
 module LaunchDarkly
 # An object returned by {LDClient#variation_detail}, combining the result of a flag evaluation with
   # an explanation of how it was calculated.
@@ -12,7 +11,8 @@ module LaunchDarkly
     # @raise [ArgumentError] if `variation_index` or `reason` is not of the correct type
     def initialize(value, variation_index, reason)
       raise ArgumentError.new("variation_index must be a number") if !variation_index.nil? && !(variation_index.is_a? Numeric)
-      raise ArgumentError.new("reason must be an EvaluationReason") if !(reason.is_a? EvaluationReason)
+      raise ArgumentError.new("reason must be an EvaluationReason") unless reason.is_a? EvaluationReason
+
       @value = value
       @variation_index = variation_index
       @reason = reason
@@ -70,20 +70,20 @@ module LaunchDarkly
   class EvaluationReason
     # Value for {#kind} indicating that the flag was off and therefore returned its configured off value.
     OFF = :OFF
-    
-    # Value for {#kind} indicating that the flag was on but the user did not match any targets or rules.
+
+    # Value for {#kind} indicating that the flag was on but the context did not match any targets or rules.
     FALLTHROUGH = :FALLTHROUGH
-    
-    # Value for {#kind} indicating that the user key was specifically targeted for this flag.
+
+    # Value for {#kind} indicating that the context key was specifically targeted for this flag.
     TARGET_MATCH = :TARGET_MATCH
-    
-    # Value for {#kind} indicating that the user matched one of the flag's rules.
+
+    # Value for {#kind} indicating that the context matched one of the flag's rules.
     RULE_MATCH = :RULE_MATCH
-    
+
     # Value for {#kind} indicating that the flag was considered off because it had at least one
     # prerequisite flag that either was off or did not return the desired variation.
     PREREQUISITE_FAILED = :PREREQUISITE_FAILED
-    
+
     # Value for {#kind} indicating that the flag could not be evaluated, e.g. because it does not exist
     # or due to an unexpected error. In this case the result value will be the application default value
     # that the caller passed to the client. Check {#error_kind} for more details on the problem.
@@ -100,8 +100,12 @@ module LaunchDarkly
     # a rule specified a nonexistent  variation. An error message will always be logged in this case.
     ERROR_MALFORMED_FLAG = :MALFORMED_FLAG
 
-    # Value for {#error_kind} indicating that the caller passed `nil` for the user parameter, or the
-    # user lacked a key.
+    # Value for {#error_kind} indicating that there was an inconsistency between the expected type of the flag, and the
+    # actual type of the variation evaluated.
+    ERROR_WRONG_TYPE = :WRONG_TYPE
+
+    # Value for {#error_kind} indicating that the caller passed `nil` for the context parameter, or the
+    # context was invalid.
     ERROR_USER_NOT_SPECIFIED = :USER_NOT_SPECIFIED
 
     # Value for {#error_kind} indicating that an unexpected exception stopped flag evaluation. An error
@@ -141,7 +145,7 @@ module LaunchDarkly
     # querying at least one Big Segment. Otherwise it returns `nil`. Possible values are defined by
     # {BigSegmentsStatus}.
     #
-    # Big Segments are a specific kind of user segments. For more information, read the LaunchDarkly
+    # Big Segments are a specific kind of context segments. For more information, read the LaunchDarkly
     # documentation: https://docs.launchdarkly.com/home/users/big-segments
     # @return [Symbol]
     attr_reader :big_segments_status
@@ -176,9 +180,9 @@ module LaunchDarkly
     # @return [EvaluationReason]
     # @raise [ArgumentError] if `rule_index` is not a number or `rule_id` is not a string
     def self.rule_match(rule_index, rule_id, in_experiment=false)
-      raise ArgumentError.new("rule_index must be a number") if !(rule_index.is_a? Numeric)
+      raise ArgumentError.new("rule_index must be a number") unless rule_index.is_a? Numeric
       raise ArgumentError.new("rule_id must be a string") if !rule_id.nil? && !(rule_id.is_a? String) # in test data, ID could be nil
-      
+
       if in_experiment
         er = new(:RULE_MATCH, rule_index, rule_id, nil, nil, true)
       else
@@ -193,7 +197,7 @@ module LaunchDarkly
     # @return [EvaluationReason]
     # @raise [ArgumentError] if `prerequisite_key` is nil or not a string
     def self.prerequisite_failed(prerequisite_key)
-      raise ArgumentError.new("prerequisite_key must be a string") if !(prerequisite_key.is_a? String)
+      raise ArgumentError.new("prerequisite_key must be a string") unless prerequisite_key.is_a? String
       new(:PREREQUISITE_FAILED, nil, nil, prerequisite_key, nil)
     end
 
@@ -203,7 +207,7 @@ module LaunchDarkly
     # @return [EvaluationReason]
     # @raise [ArgumentError] if `error_kind` is not a symbol
     def self.error(error_kind)
-      raise ArgumentError.new("error_kind must be a symbol") if !(error_kind.is_a? Symbol)
+      raise ArgumentError.new("error_kind must be a symbol") unless error_kind.is_a? Symbol
       e = @@error_instances[error_kind]
       e.nil? ? make_error(error_kind) : e
     end
@@ -279,7 +283,7 @@ module LaunchDarkly
       else
         { kind: @kind }
       end
-      if !@big_segments_status.nil?
+      unless @big_segments_status.nil?
         ret[:bigSegmentsStatus] = @big_segments_status
       end
       ret
@@ -288,7 +292,7 @@ module LaunchDarkly
     # Same as {#as_json}, but converts the JSON structure into a string.
     # @return [String]
     def to_json(*a)
-      as_json.to_json(a)
+      as_json.to_json(*a)
     end
 
     # Allows this object to be treated as a hash corresponding to its JSON representation. For
@@ -327,9 +331,9 @@ module LaunchDarkly
       @kind = kind.to_sym
       @rule_index = rule_index
       @rule_id = rule_id
-      @rule_id.freeze if !rule_id.nil?
+      @rule_id.freeze unless rule_id.nil?
       @prerequisite_key = prerequisite_key
-      @prerequisite_key.freeze if !prerequisite_key.nil?
+      @prerequisite_key.freeze unless prerequisite_key.nil?
       @error_kind = error_kind
       @in_experiment = in_experiment
       @big_segments_status = big_segments_status
@@ -348,7 +352,7 @@ module LaunchDarkly
       ERROR_FLAG_NOT_FOUND => make_error(ERROR_FLAG_NOT_FOUND),
       ERROR_MALFORMED_FLAG => make_error(ERROR_MALFORMED_FLAG),
       ERROR_USER_NOT_SPECIFIED => make_error(ERROR_USER_NOT_SPECIFIED),
-      ERROR_EXCEPTION => make_error(ERROR_EXCEPTION)
+      ERROR_EXCEPTION => make_error(ERROR_EXCEPTION),
     }
   end