launchdarkly-server-sdk 6.1.1 → 6.4.0

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

@@ -0,0 +1,177 @@
+require "ldclient-rb/impl/evaluator_helpers"
+
+module LaunchDarkly
+  module Impl
+    module DataModelPreprocessing
+      #
+      # 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 [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
+        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
+
+      # Base class for all of the preprocessed data classes we embed in our data model. Using this class
+      # ensures that none of its properties will be included in JSON representations. It also overrides
+      # == to say that it is always equal with another instance of the same class; equality tests on
+      # this class are only ever done in test code, and we want the contents of these classes to be
+      # ignored in test code unless we are looking at specific attributes.
+      class PreprocessedDataBase
+        def as_json(*)
+          nil
+        end
+        
+        def to_json(*a)
+          "null"
+        end
+
+        def ==(other)
+          other.class == self.class
+        end
+      end
+
+      class FlagPreprocessed < PreprocessedDataBase
+        def initialize(off_result, fallthrough_factory)
+          @off_result = off_result
+          @fallthrough_factory = fallthrough_factory
+        end
+
+        # @return [EvalResultsForSingleVariation]
+        attr_reader :off_result
+        # @return [EvalResultFactoryMultiVariations]
+        attr_reader :fallthrough_factory
+      end
+
+      class PrerequisitePreprocessed < PreprocessedDataBase
+        def initialize(failed_result)
+          @failed_result = failed_result
+        end
+
+        # @return [EvalResultsForSingleVariation]
+        attr_reader :failed_result
+      end
+
+      class TargetPreprocessed < PreprocessedDataBase
+        def initialize(match_result)
+          @match_result = match_result
+        end
+
+        # @return [EvalResultsForSingleVariation]
+        attr_reader :match_result
+      end
+
+      class FlagRulePreprocessed < PreprocessedDataBase
+        def initialize(all_match_results)
+          @all_match_results = all_match_results
+        end
+
+        # @return [EvalResultsForSingleVariation]
+        attr_reader :all_match_results
+      end
+
+      class Preprocessor
+        def initialize(logger = nil)
+          @logger = logger
+        end
+
+        def preprocess_item!(kind, item)
+          if kind.eql? FEATURES
+            preprocess_flag!(item)
+          elsif kind.eql? SEGMENTS
+            preprocess_segment!(item)
+          end
+        end
+
+        def preprocess_all_items!(kind, items_map)
+          return items_map if !items_map
+          items_map.each do |key, item|
+            preprocess_item!(kind, item)
+          end
+        end
+
+        def preprocess_flag!(flag)
+          flag[:_preprocessed] = FlagPreprocessed.new(
+            EvaluatorHelpers.off_result(flag),
+            precompute_multi_variation_results(flag, EvaluationReason::fallthrough(false), EvaluationReason::fallthrough(true))
+          )
+          (flag[:prerequisites] || []).each do |prereq|
+            preprocess_prerequisite!(prereq, flag)
+          end
+          (flag[:targets] || []).each do |target|
+            preprocess_target!(target, flag)
+          end
+          rules = flag[:rules]
+          (rules || []).each_index do |index|
+            preprocess_flag_rule!(rules[index], index, flag)
+          end
+        end
+  
+        def preprocess_segment!(segment)
+          # nothing to do for segments currently
+        end
+  
+        private def preprocess_prerequisite!(prereq, flag)
+          prereq[:_preprocessed] = PrerequisitePreprocessed.new(
+            EvaluatorHelpers.prerequisite_failed_result(prereq, flag, @logger)
+          )
+        end
+  
+        private def preprocess_target!(target, flag)
+          target[:_preprocessed] = TargetPreprocessed.new(
+            EvaluatorHelpers.target_match_result(target, flag, @logger)
+          )
+        end
+  
+        private def preprocess_flag_rule!(rule, index, flag)
+          match_reason = EvaluationReason::rule_match(index, rule[:id])
+          match_reason_in_experiment = EvaluationReason::rule_match(index, rule[:id], true)
+          rule[:_preprocessed] = FlagRulePreprocessed.new(
+            precompute_multi_variation_results(flag, match_reason, match_reason_in_experiment)
+          )
+        end
+  
+        private def 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/serialization.rb

@@ -1,13 +1,14 @@
+require "ldclient-rb/impl/model/preprocessed_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)
+      def self.deserialize(kind, json, logger = nil)
         return nil if json.nil?
         item = JSON.parse(json, symbolize_names: true)
-        postprocess_item_after_deserializing!(kind, item)
+        DataModelPreprocessing::Preprocessor.new(logger).preprocess_item!(kind, item)
         item
       end
 
@@ -18,45 +19,14 @@ module LaunchDarkly
       end
 
       # Translates a { flags: ..., segments: ... } object received from LaunchDarkly to the data store format.
-      def self.make_all_store_data(received_data)
+      def self.make_all_store_data(received_data, logger = nil)
+        preprocessor = DataModelPreprocessing::Preprocessor.new(logger)
         flags = received_data[:flags]
-        postprocess_items_after_deserializing!(FEATURES, flags)
+        preprocessor.preprocess_all_items!(FEATURES, flags)
         segments = received_data[:segments]
-        postprocess_items_after_deserializing!(SEGMENTS, segments)
+        preprocessor.preprocess_all_items!(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
-      end
     end
   end
 end

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

@@ -0,0 +1,47 @@
+require "ldclient-rb/util"
+
+require "concurrent/atomics"
+
+module LaunchDarkly
+  module Impl
+    class RepeatingTask
+      def initialize(interval, start_delay, task, logger)
+        @interval = interval
+        @start_delay = start_delay
+        @task = task
+        @logger = logger
+        @stopped = Concurrent::AtomicBoolean.new(false)
+        @worker = nil
+      end
+
+      def start
+        @worker = Thread.new do
+          if @start_delay
+            sleep(@start_delay)
+          end
+          while !@stopped.value do
+            started_at = Time.now
+            begin
+              @task.call
+            rescue => e
+              LaunchDarkly::Util.log_exception(@logger, "Uncaught exception from repeating task", e)
+            end
+            delta = @interval - (Time.now - started_at)
+            if delta > 0
+              sleep(delta)
+            end
+          end
+        end
+      end
+
+      def stop
+        if @stopped.make_true
+          if @worker && @worker.alive? && @worker != Thread.current
+            @worker.run  # causes the thread to wake up if it's currently in a sleep
+            @worker.join
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,10 @@
-
 module LaunchDarkly
   module Impl
     module Util
+      def self.is_bool(aObject)
+         [true,false].include? aObject
+      end
+
       def self.current_time_millis
         (Time.now.to_f * 1000).to_i
       end
@@ -12,8 +15,66 @@ module LaunchDarkly
           ret["X-LaunchDarkly-Wrapper"] = config.wrapper_name +
             (config.wrapper_version ? "/" + config.wrapper_version : "")
         end
+
+        app_value = application_header_value config.application
+        ret["X-LaunchDarkly-Tags"] = app_value unless app_value.nil? || app_value.empty?
+
         ret
       end
+
+      #
+      # Generate an HTTP Header value containing the application meta information (@see #application).
+      #
+      # @return [String]
+      #
+      def self.application_header_value(application)
+        parts = []
+        unless  application[:id].empty?
+          parts << "application-id/#{application[:id]}"
+        end
+
+        unless  application[:version].empty?
+          parts << "application-version/#{application[:version]}"
+        end
+
+        parts.join(" ")
+      end
+
+      #
+      # @param value [String]
+      # @param name [Symbol]
+      # @param logger [Logger]
+      # @return [String]
+      #
+      def self.validate_application_value(value, name, logger)
+        value = value.to_s
+
+        return "" if value.empty?
+
+        if value.length > 64
+          logger.warn { "Value of application[#{name}] was longer than 64 characters and was discarded" }
+          return ""
+        end
+
+        if value.match(/[^a-zA-Z0-9._-]/)
+          logger.warn { "Value of application[#{name}] contained invalid characters and was discarded" }
+          return ""
+        end
+
+        value
+      end
+
+      #
+      # @param app [Hash]
+      # @param logger [Logger]
+      # @return [Hash]
+      #
+      def self.validate_application_info(app, logger)
+        {
+          id: validate_application_value(app[:id], :id, logger),
+          version: validate_application_value(app[:version], :version, logger),
+        }
+      end
     end
   end
 end

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

@@ -3,6 +3,13 @@ require "ldclient-rb/integrations/util/store_wrapper"
 
 module LaunchDarkly
   module Integrations
+    #
+    # Integration with [Consul](https://www.consul.io/).
+    #
+    # Note that in order to use this integration, you must first install the gem `diplomat`.
+    #
+    # @since 5.5.0
+    #
     module Consul
       #
       # Default value for the `prefix` option for {new_feature_store}.
@@ -29,7 +36,7 @@ module LaunchDarkly
       # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
       # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
       #
-      def self.new_feature_store(opts, &block)
+      def self.new_feature_store(opts = {})
         core = LaunchDarkly::Impl::Integrations::Consul::ConsulFeatureStoreCore.new(opts)
         return LaunchDarkly::Integrations::Util::CachingStoreWrapper.new(core, opts)
       end

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

@@ -3,11 +3,19 @@ require "ldclient-rb/integrations/util/store_wrapper"
 
 module LaunchDarkly
   module Integrations
+    #
+    # Integration with [DynamoDB](https://aws.amazon.com/dynamodb/).
+    #
+    # Note that in order to use this integration, you must first install one of the AWS SDK gems: either
+    # `aws-sdk-dynamodb`, or the full `aws-sdk`.
+    #
+    # @since 5.5.0
+    #
     module DynamoDB
       #
       # Creates a DynamoDB-backed persistent feature store. For more details about how and why you can
       # use a persistent feature store, see the
-      # [SDK reference guide](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+      # [SDK reference guide](https://docs.launchdarkly.com/sdk/features/storing-data#ruby).
       #
       # To use this method, you must first install one of the AWS SDK gems: either `aws-sdk-dynamodb`, or
       # the full `aws-sdk`. Then, put the object returned by this method into the `feature_store` property
@@ -38,9 +46,46 @@ module LaunchDarkly
       # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
       # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
       #
-      def self.new_feature_store(table_name, opts)
+      def self.new_feature_store(table_name, opts = {})
         core = LaunchDarkly::Impl::Integrations::DynamoDB::DynamoDBFeatureStoreCore.new(table_name, opts)
-        return LaunchDarkly::Integrations::Util::CachingStoreWrapper.new(core, opts)
+        LaunchDarkly::Integrations::Util::CachingStoreWrapper.new(core, opts)
+      end
+
+      #
+      # Creates a DynamoDB-backed Big Segment store.
+      #
+      # Big Segments are a specific type of user segments. For more information, read the LaunchDarkly
+      # documentation: https://docs.launchdarkly.com/home/users/big-segments
+      #
+      # To use this method, you must first install one of the AWS SDK gems: either `aws-sdk-dynamodb`, or
+      # the full `aws-sdk`. Then, put the object returned by this method into the `store` property of your
+      # Big Segments configuration (see `Config`).
+      #
+      # @example Configuring Big Segments
+      #     store = LaunchDarkly::Integrations::DynamoDB::new_big_segment_store("my-table-name")
+      #     config = LaunchDarkly::Config.new(big_segments: LaunchDarkly::BigSegmentsConfig.new(store: store)
+      #     client = LaunchDarkly::LDClient.new(my_sdk_key, config)
+      #
+      # Note that the specified table must already exist in DynamoDB. It must have a partition key called
+      # "namespace", and a sort key called "key" (both strings). The SDK does not create the table
+      # automatically because it has no way of knowing what additional properties (such as permissions
+      # and throughput) you would want it to have.
+      #
+      # By default, the DynamoDB client will try to get your AWS credentials and region name from
+      # environment variables and/or local configuration files, as described in the AWS SDK documentation.
+      # You can also specify any supported AWS SDK options in `dynamodb_opts`-- or, provide an
+      # already-configured DynamoDB client in `existing_client`.
+      #
+      # @param opts [Hash] the configuration options (these are all the same as for `new_feature_store`,
+      #   except that there are no caching parameters)
+      # @option opts [Hash] :dynamodb_opts  options to pass to the DynamoDB client constructor (ignored if you specify `:existing_client`)
+      # @option opts [Object] :existing_client  an already-constructed DynamoDB client for the feature store to use
+      # @option opts [String] :prefix  namespace prefix to add to all keys used by LaunchDarkly
+      # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
+      # @return [LaunchDarkly::Interfaces::BigSegmentStore]  a Big Segment store object
+      #
+      def self.new_big_segment_store(table_name, opts)
+        LaunchDarkly::Impl::Integrations::DynamoDB::DynamoDBBigSegmentStore.new(table_name, opts)
       end
     end
   end

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

@@ -0,0 +1,108 @@
+require 'ldclient-rb/impl/integrations/file_data_source'
+
+module LaunchDarkly
+  module Integrations
+    #
+    # Provides a way to use local files as a source of feature flag state. This allows using a
+    # predetermined feature flag state without an actual LaunchDarkly connection.
+    #
+    # Reading flags from a file is only intended for pre-production environments. Production
+    # environments should always be configured to receive flag updates from LaunchDarkly.
+    #
+    # To use this component, call {FileData#data_source}, and store its return value in the
+    # {Config#data_source} property of your LaunchDarkly client configuration. In the options
+    # to `data_source`, set `paths` to the file path(s) of your data file(s):
+    #
+    #     file_source = LaunchDarkly::Integrations::FileData.data_source(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?}.
+    #
+    # 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.
+    #
+    # 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://sdk.launchdarkly.com/sdk/latest-all
+    # ```
+    #
+    # The output will look something like this (but with many more properties):
+    #
+    #     {
+    #       "flags": {
+    #         "flag-key-1": {
+    #           "key": "flag-key-1",
+    #           "on": true,
+    #           "variations": [ "a", "b" ]
+    #         }
+    #       },
+    #       "segments": {
+    #         "segment-key-1": {
+    #           "key": "segment-key-1",
+    #           "includes": [ "user-key-1" ]
+    #         }
+    #       }
+    #     }
+    #
+    # Data in this format allows the SDK to exactly duplicate all the kinds of flag behavior supported
+    # by LaunchDarkly. However, in many cases you will not need this complexity, but will just want to
+    # set specific flag keys to specific values. For that, you can use a much simpler format:
+    #
+    #     {
+    #       "flagValues": {
+    #         "my-string-flag-key": "value-1",
+    #         "my-boolean-flag-key": true,
+    #         "my-integer-flag-key": 3
+    #       }
+    #     }
+    #
+    # Or, in YAML:
+    #
+    #     flagValues:
+    #       my-string-flag-key: "value-1"
+    #       my-boolean-flag-key: true
+    #       my-integer-flag-key: 1
+    #
+    # It is also possible to specify both "flags" and "flagValues", if you want some flags
+    # to have simple values and others to have complex behavior. However, it is an error to use the
+    # same flag key or segment key more than once, either in a single file or across multiple files.
+    #
+    # If the data source encounters any error in any file-- malformed content, a missing file, or a
+    # duplicate key-- it will not load flags from any of the files.      
+    #
+    module FileData
+      #
+      # Returns a factory for the file data source component.
+      #
+      # @param options [Hash] the configuration options
+      # @option options [Array] :paths  The paths of the source files for loading flag data. These
+      #   may be absolute paths or relative to the current working directory.
+      # @option options [Boolean] :auto_update  True if the data source should watch for changes to
+      #   the source file(s) and reload flags whenever there is a change. Auto-updating will only
+      #   work if all of the files you specified have valid directory paths at startup time.
+      #   Note that the default implementation of this feature is based on polling the filesystem,
+      #   which may not perform well. If you install the 'listen' gem (not included by default, to
+      #   avoid adding unwanted dependencies to the SDK), its native file watching mechanism will be
+      #   used instead. However, 'listen' will not be used in JRuby 9.1 due to a known instability.
+      # @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.data_source(options={})
+        return lambda { |sdk_key, config|
+          Impl::Integrations::FileDataSourceImpl.new(config.feature_store, config.logger, options) }
+      end
+    end
+  end
+end

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

@@ -2,6 +2,14 @@ require "ldclient-rb/redis_store"  # eventually we will just refer to impl/integ
 
 module LaunchDarkly
   module Integrations
+    #
+    # Integration with [Redis](https://redis.io/).
+    #
+    # Note that in order to use this integration, you must first install the `redis` and `connection-pool`
+    # gems.
+    #
+    # @since 5.5.0
+    #
     module Redis
       #
       # Default value for the `redis_url` option for {new_feature_store}. This points to an instance of
@@ -25,7 +33,7 @@ module LaunchDarkly
       #
       # Creates a Redis-backed persistent feature store. For more details about how and why you can
       # use a persistent feature store, see the
-      # [SDK reference guide](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+      # [SDK reference guide](https://docs.launchdarkly.com/sdk/features/storing-data#rubys).
       #
       # To use this method, you must first have the `redis` and `connection-pool` gems installed. Then,
       # put the object returned by this method into the `feature_store` property of your
@@ -50,9 +58,41 @@ module LaunchDarkly
       #   lifecycle to be independent of the SDK client
       # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
       #
-      def self.new_feature_store(opts)
+      def self.new_feature_store(opts = {})
         return RedisFeatureStore.new(opts)
       end
+
+      #
+      # Creates a Redis-backed Big Segment store.
+      #
+      # Big Segments are a specific type of user segments. For more information, read the LaunchDarkly
+      # documentation: https://docs.launchdarkly.com/home/users/big-segments
+      #
+      # To use this method, you must first have the `redis` and `connection-pool` gems installed. Then,
+      # put the object returned by this method into the `store` property of your Big Segments configuration
+      # (see `Config`).
+      #
+      # @example Configuring Big Segments
+      #     store = LaunchDarkly::Integrations::Redis::new_big_segment_store(redis_url: "redis://my-server")
+      #     config = LaunchDarkly::Config.new(big_segments: LaunchDarkly::BigSegmentsConfig.new(store: store)
+      #     client = LaunchDarkly::LDClient.new(my_sdk_key, config)
+      #
+      # @param opts [Hash] the configuration options (these are all the same as for `new_feature_store`,
+      #   except that there are no caching parameters)
+      # @option opts [String] :redis_url (default_redis_url)  URL of the Redis instance (shortcut for omitting `redis_opts`)
+      # @option opts [Hash] :redis_opts  options to pass to the Redis constructor (if you want to specify more than just `redis_url`)
+      # @option opts [String] :prefix (default_prefix)  namespace prefix to add to all hash keys used by LaunchDarkly
+      # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
+      # @option opts [Integer] :max_connections  size of the Redis connection pool
+      # @option opts [Object] :pool  custom connection pool, if desired
+      # @option opts [Boolean] :pool_shutdown_on_close whether calling `close` should shutdown the custom connection pool;
+      #   this is true by default, and should be set to false only if you are managing the pool yourself and want its
+      #   lifecycle to be independent of the SDK client
+      # @return [LaunchDarkly::Interfaces::BigSegmentStore]  a Big Segment store object
+      #
+      def self.new_big_segment_store(opts)
+        return LaunchDarkly::Impl::Integrations::Redis::RedisBigSegmentStore.new(opts)
+      end
     end
   end
 end