ldclient-rb 5.4.3 → 5.5.0

data/lib/ldclient-rb/evaluation.rb

@@ -2,7 +2,7 @@ require "date"
 require "semantic"
 
 module LaunchDarkly
-  # An object returned by `LDClient.variation_detail`, combining the result of a flag evaluation with
+  # An object returned by {LDClient#variation_detail}, combining the result of a flag evaluation with
   # an explanation of how it was calculated.
   class EvaluationDetail
     def initialize(value, variation_index, reason)
@@ -11,19 +11,66 @@ module LaunchDarkly
       @reason = reason
     end
 
-    # @return [Object] The result of the flag evaluation. This will be either one of the flag's
-    #   variations or the default value that was passed to the `variation` method.
+    #
+    # The result of the flag evaluation. This will be either one of the flag's variations, or the
+    # default value that was passed to {LDClient#variation_detail}. It is the same as the return
+    # value of {LDClient#variation}.
+    #
+    # @return [Object]
+    #
     attr_reader :value
 
-    # @return [int|nil] The index of the returned value within the flag's list of variations, e.g.
-    #   0 for the first variation - or `nil` if the default value was returned.
+    #
+    # The index of the returned value within the flag's list of variations. The first variation is
+    # 0, the second is 1, etc. This is `nil` if the default value was returned.
+    #
+    # @return [int|nil]
+    #
     attr_reader :variation_index
 
-    # @return [Hash] An object describing the main factor that influenced the flag evaluation value.
+    #
+    # An object describing the main factor that influenced the flag evaluation value.
+    #
+    # This object is currently represented as a Hash, which may have the following keys:
+    #
+    # `:kind`: The general category of reason. Possible values:
+    #
+    # * `'OFF'`: the flag was off and therefore returned its configured off value
+    # * `'FALLTHROUGH'`: the flag was on but the user did not match any targets or rules
+    # * `'TARGET_MATCH'`: the user key was specifically targeted for this flag
+    # * `'RULE_MATCH'`: the user matched one of the flag's rules
+    # * `'PREREQUISITE_FAILED`': the flag was considered off because it had at least one
+    # prerequisite flag that either was off or did not return the desired variation
+    # * `'ERROR'`: the flag could not be evaluated, so the default value was returned
+    #
+    # `:ruleIndex`: If the kind was `RULE_MATCH`, this is the positional index of the
+    # matched rule (0 for the first rule).
+    #
+    # `:ruleId`: If the kind was `RULE_MATCH`, this is the rule's unique identifier.
+    #
+    # `:prerequisiteKey`: If the kind was `PREREQUISITE_FAILED`, this is the flag key of
+    # the prerequisite flag that failed.
+    #
+    # `:errorKind`: If the kind was `ERROR`, this indicates the type of error:
+    #
+    # * `'CLIENT_NOT_READY'`: the caller tried to evaluate a flag before the client had
+    # successfully initialized
+    # * `'FLAG_NOT_FOUND'`: the caller provided a flag key that did not match any known flag
+    # * `'MALFORMED_FLAG'`: there was an internal inconsistency in the flag data, e.g. a
+    # rule specified a nonexistent variation
+    # * `'USER_NOT_SPECIFIED'`: the user object or user key was not provied
+    # * `'EXCEPTION'`: an unexpected exception stopped flag evaluation
+    #
+    # @return [Hash]
+    #
     attr_reader :reason
 
-    # @return [boolean] True if the flag evaluated to the default value rather than to one of its
-    #   variations.
+    #
+    # Tests whether the flag evaluation returned a default value. This is the same as checking
+    # whether {#variation_index} is nil.
+    #
+    # @return [Boolean]
+    #
     def default_value?
       variation_index.nil?
     end
@@ -33,6 +80,7 @@ module LaunchDarkly
     end
   end
 
+  # @private
   module Evaluation
     BUILTINS = [:key, :ip, :country, :email, :firstName, :lastName, :avatar, :name, :anonymous]
 

data/lib/ldclient-rb/event_summarizer.rb

@@ -1,11 +1,14 @@
 
 module LaunchDarkly
+  # @private
   EventSummary = Struct.new(:start_date, :end_date, :counters)
 
   # Manages the state of summarizable information for the EventProcessor, including the
   # event counters and user deduplication. Note that the methods of this class are
   # deliberately not thread-safe; the EventProcessor is responsible for enforcing
   # synchronization across both the summarizer and the event queue.
+  #
+  # @private
   class EventSummarizer
     def initialize
       clear

data/lib/ldclient-rb/events.rb

@@ -9,6 +9,10 @@ module LaunchDarkly
   MAX_FLUSH_WORKERS = 5
   CURRENT_SCHEMA_VERSION = 3
 
+  private_constant :MAX_FLUSH_WORKERS
+  private_constant :CURRENT_SCHEMA_VERSION
+
+  # @private
   class NullEventProcessor
     def add_event(event)
     end
@@ -20,6 +24,7 @@ module LaunchDarkly
     end
   end
 
+  # @private
   class EventMessage
     def initialize(event)
       @event = event
@@ -27,12 +32,15 @@ module LaunchDarkly
     attr_reader :event
   end
 
+  # @private
   class FlushMessage
   end
 
+  # @private
   class FlushUsersMessage
   end
 
+  # @private
   class SynchronousMessage
     def initialize
       @reply = Concurrent::Semaphore.new(0)
@@ -47,12 +55,15 @@ module LaunchDarkly
     end
   end
 
+  # @private
   class TestSyncMessage < SynchronousMessage
   end
 
+  # @private
   class StopMessage < SynchronousMessage
   end
 
+  # @private
   class EventProcessor
     def initialize(sdk_key, config, client = nil)
       @queue = Queue.new
@@ -99,6 +110,7 @@ module LaunchDarkly
     end
   end
 
+  # @private
   class EventDispatcher
     def initialize(queue, sdk_key, config, client)
       @sdk_key = sdk_key
@@ -252,8 +264,10 @@ module LaunchDarkly
     end
   end
 
+  # @private
   FlushPayload = Struct.new(:events, :summary)
 
+  # @private
   class EventBuffer
     def initialize(capacity, logger)
       @capacity = capacity
@@ -290,6 +304,7 @@ module LaunchDarkly
     end
   end
 
+  # @private
   class EventPayloadSendTask
     def run(sdk_key, config, client, payload, formatter)
       events_out = formatter.make_output_events(payload.events, payload.summary)
@@ -327,6 +342,7 @@ module LaunchDarkly
     end
   end
 
+  # @private
   class EventOutputFormatter
     def initialize(config)
       @inline_users = config.inline_users_in_events

data/lib/ldclient-rb/expiring_cache.rb

@@ -6,6 +6,7 @@ module LaunchDarkly
   #   * made thread-safe
   #   * removed many unused methods
   #   * reading a key does not reset its expiration time, only writing
+  # @private
   class ExpiringCache
     def initialize(max_size, ttl)
       @max_size = max_size

data/lib/ldclient-rb/file_data_source.rb

@@ -7,12 +7,15 @@ module LaunchDarkly
   # To avoid pulling in 'listen' and its transitive dependencies for people who aren't using the
   # file data source or who don't need auto-updating, we only enable auto-update if the 'listen'
   # gem has been provided by the host app.
+  # @private
   @@have_listen = false
   begin
     require 'listen'
     @@have_listen = true
   rescue LoadError
   end
+
+  # @private
   def self.have_listen?
     @@have_listen
   end
@@ -22,30 +25,32 @@ module LaunchDarkly
   # used in a test environment, to operate using a predetermined feature flag state without an
   # actual LaunchDarkly connection.
   #
-  # To use this component, call `FileDataSource.factory`, and store its return value in the
-  # `update_processor_factory` property of your LaunchDarkly client configuration. In the options
+  # To use this component, call {FileDataSource#factory}, and store its return value in the
+  # {Config#data_source} property of your LaunchDarkly client configuration. In the options
   # to `factory`, set `paths` to the file path(s) of your data file(s):
   #
-  #     factory = FileDataSource.factory(paths: [ myFilePath ])
-  #     config = LaunchDarkly::Config.new(update_processor_factory: factory)
+  #     file_source = FileDataSource.factory(paths: [ myFilePath ])
+  #     config = LaunchDarkly::Config.new(data_source: file_source)
   #
   # This will cause the client not to connect to LaunchDarkly to get feature flags. The
   # client may still make network connections to send analytics events, unless you have disabled
-  # this with Config.send_events or Config.offline.
+  # this with {Config#send_events} or {Config#offline?}.
   #
   # Flag data files can be either JSON or YAML. They contain an object with three possible
   # properties:
   #
-  # - "flags": Feature flag definitions.
-  # - "flagValues": Simplified feature flags that contain only a value.
-  # - "segments": User segment definitions.
+  # - `flags`: Feature flag definitions.
+  # - `flagValues`: Simplified feature flags that contain only a value.
+  # - `segments`: User segment definitions.
   #
-  # The format of the data in "flags" and "segments" is defined by the LaunchDarkly application
+  # The format of the data in `flags` and `segments` is defined by the LaunchDarkly application
   # and is subject to change. Rather than trying to construct these objects yourself, it is simpler
   # to request existing flags directly from the LaunchDarkly server in JSON format, and use this
   # output as the starting point for your file. In Linux you would do this:
   #
-  #    curl -H "Authorization: {your sdk key}" https://app.launchdarkly.com/sdk/latest-all
+  # ```
+  #     curl -H "Authorization: YOUR_SDK_KEY" https://app.launchdarkly.com/sdk/latest-all
+  # ```
   #
   # The output will look something like this (but with many more properties):
   #
@@ -108,14 +113,14 @@ module LaunchDarkly
     # @option options [Float] :poll_interval  The minimum interval, in seconds, between checks for
     #   file modifications - used only if auto_update is true, and if the native file-watching
     #   mechanism from 'listen' is not being used. The default value is 1 second.
+    # @return an object that can be stored in {Config#data_source}
     #
     def self.factory(options={})
-      return Proc.new do |sdk_key, config|
-        FileDataSourceImpl.new(config.feature_store, config.logger, options)
-      end
+      return lambda { |sdk_key, config| FileDataSourceImpl.new(config.feature_store, config.logger, options) }
     end
   end
 
+  # @private
   class FileDataSourceImpl
     def initialize(feature_store, logger, options={})
       @feature_store = feature_store

data/lib/ldclient-rb/flags_state.rb

@@ -3,8 +3,8 @@ require 'json'
 module LaunchDarkly
   #
   # A snapshot of the state of all feature flags with regard to a specific user, generated by
-  # calling the client's all_flags_state method. Serializing this object to JSON using
-  # JSON.generate (or the to_json method) will produce the appropriate data structure for
+  # calling the {LDClient#all_flags_state}. Serializing this object to JSON using
+  # `JSON.generate` (or the `to_json` method) will produce the appropriate data structure for
   # bootstrapping the LaunchDarkly JavaScript client.
   #
   class FeatureFlagsState
@@ -15,6 +15,7 @@ module LaunchDarkly
     end
 
     # Used internally to build the state map.
+    # @private
     def add_flag(flag, value, variation, reason = nil, details_only_if_tracked = false)
       key = flag[:key]
       @flag_values[key] = value

data/lib/ldclient-rb/impl.rb

@@ -0,0 +1,13 @@
+
+module LaunchDarkly
+  #
+  # Internal implementation classes. Everything in this module should be considered unsupported
+  # and subject to change.
+  #
+  # @since 5.5.0
+  # @private
+  #
+  module Impl
+    # code is in ldclient-rb/impl/
+  end
+end

data/lib/ldclient-rb/impl/integrations/consul_impl.rb

@@ -0,0 +1,158 @@
+require "json"
+
+module LaunchDarkly
+  module Impl
+    module Integrations
+      module Consul
+        #
+        # Internal implementation of the Consul feature store, intended to be used with CachingStoreWrapper.
+        #
+        class ConsulFeatureStoreCore
+          begin
+            require "diplomat"
+            CONSUL_ENABLED = true
+          rescue ScriptError, StandardError
+            CONSUL_ENABLED = false
+          end
+
+          def initialize(opts)
+            if !CONSUL_ENABLED
+              raise RuntimeError.new("can't use Consul feature store without the 'diplomat' gem")
+            end
+
+            @prefix = (opts[:prefix] || LaunchDarkly::Integrations::Consul.default_prefix) + '/'
+            @logger = opts[:logger] || Config.default_logger
+            Diplomat.configuration = opts[:consul_config] if !opts[:consul_config].nil?
+            Diplomat.configuration.url = opts[:url] if !opts[:url].nil?
+            @logger.info("ConsulFeatureStore: using Consul host at #{Diplomat.configuration.url}")
+          end
+
+          def init_internal(all_data)
+            # Start by reading the existing keys; we will later delete any of these that weren't in all_data.
+            unused_old_keys = Set.new
+            keys = Diplomat::Kv.get(@prefix, { keys: true, recurse: true }, :return)
+            unused_old_keys.merge(keys) if keys != ""
+
+            ops = []
+            num_items = 0
+
+            # Insert or update every provided item
+            all_data.each do |kind, items|
+              items.values.each do |item|
+                value = item.to_json
+                key = item_key(kind, item[:key])
+                ops.push({ 'KV' => { 'Verb' => 'set', 'Key' => key, 'Value' => value } })
+                unused_old_keys.delete(key)
+                num_items = num_items + 1
+              end
+            end
+
+            # Now delete any previously existing items whose keys were not in the current data
+            unused_old_keys.each do |key|
+              ops.push({ 'KV' => { 'Verb' => 'delete', 'Key' => key } })
+            end
+    
+            # Now set the special key that we check in initialized_internal?
+            ops.push({ 'KV' => { 'Verb' => 'set', 'Key' => inited_key, 'Value' => '' } })
+            
+            ConsulUtil.batch_operations(ops)
+
+            @logger.info { "Initialized database with #{num_items} items" }
+          end
+
+          def get_internal(kind, key)
+            value = Diplomat::Kv.get(item_key(kind, key), {}, :return)  # :return means "don't throw an error if not found"
+            (value.nil? || value == "") ? nil : JSON.parse(value, symbolize_names: true)
+          end
+
+          def get_all_internal(kind)
+            items_out = {}
+            results = Diplomat::Kv.get(kind_key(kind), { recurse: true }, :return)
+            (results == "" ? [] : results).each do |result|
+              value = result[:value]
+              if !value.nil?
+                item = JSON.parse(value, symbolize_names: true)
+                items_out[item[:key].to_sym] = item
+              end
+            end
+            items_out
+          end
+
+          def upsert_internal(kind, new_item)
+            key = item_key(kind, new_item[:key])
+            json = new_item.to_json
+
+            # We will potentially keep retrying indefinitely until someone's write succeeds
+            while true
+              old_value = Diplomat::Kv.get(key, { decode_values: true }, :return)
+              if old_value.nil? || old_value == ""
+                mod_index = 0
+              else
+                old_item = JSON.parse(old_value[0]["Value"], symbolize_names: true)
+                # Check whether the item is stale. If so, don't do the update (and return the existing item to
+                # FeatureStoreWrapper so it can be cached)
+                if old_item[:version] >= new_item[:version]
+                  return old_item
+                end
+                mod_index = old_value[0]["ModifyIndex"]
+              end
+
+              # Otherwise, try to write. We will do a compare-and-set operation, so the write will only succeed if
+              # the key's ModifyIndex is still equal to the previous value. If the previous ModifyIndex was zero,
+              # it means the key did not previously exist and the write will only succeed if it still doesn't exist.
+              success = Diplomat::Kv.put(key, json, cas: mod_index)
+              return new_item if success
+
+              # If we failed, retry the whole shebang
+              @logger.debug { "Concurrent modification detected, retrying" }
+            end
+          end
+
+          def initialized_internal?
+            # Unfortunately we need to use exceptions here, instead of the :return parameter, because with
+            # :return there's no way to distinguish between a missing value and an empty string.
+            begin
+              Diplomat::Kv.get(inited_key, {})
+              true
+            rescue Diplomat::KeyNotFound
+              false
+            end
+          end
+
+          def stop
+            # There's no Consul client instance to dispose of
+          end
+
+          private
+
+          def item_key(kind, key)
+            kind_key(kind) + key.to_s
+          end
+
+          def kind_key(kind)
+            @prefix + kind[:namespace] + '/'
+          end
+          
+          def inited_key
+            @prefix + '$inited'
+          end
+        end
+
+        class ConsulUtil
+          #
+          # Submits as many transactions as necessary to submit all of the given operations.
+          # The ops array is consumed.
+          #
+          def self.batch_operations(ops)
+            batch_size = 64  # Consul can only do this many at a time
+            while true
+              chunk = ops.shift(batch_size)
+              break if chunk.empty?
+              Diplomat::Kv.txn(chunk)
+            end
+          end
+        end
+      end
+    end
+  end
+end