launchdarkly-server-sdk 6.2.5 → 6.3.2

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

@@ -0,0 +1,212 @@
+require 'ldclient-rb/in_memory_store'
+require 'ldclient-rb/util'
+
+require 'concurrent/atomics'
+require 'json'
+require 'yaml'
+require 'pathname'
+
+module LaunchDarkly
+  module Impl
+    module Integrations
+      class FileDataSourceImpl
+        # 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.
+        @@have_listen = false
+        begin
+          require 'listen'
+          @@have_listen = true
+        rescue LoadError
+        end
+
+        def initialize(feature_store, logger, options={})
+          @feature_store = feature_store
+          @logger = logger
+          @paths = options[:paths] || []
+          if @paths.is_a? String
+            @paths = [ @paths ]
+          end
+          @auto_update = options[:auto_update]
+          if @auto_update && @@have_listen && !options[:force_polling] # force_polling is used only for tests
+            # We have seen unreliable behavior in the 'listen' gem in JRuby 9.1 (https://github.com/guard/listen/issues/449).
+            # Therefore, on that platform we'll fall back to file polling instead.
+            if defined?(JRUBY_VERSION) && JRUBY_VERSION.start_with?("9.1.")
+              @use_listen = false
+            else
+              @use_listen = true
+            end
+          end
+          @poll_interval = options[:poll_interval] || 1
+          @initialized = Concurrent::AtomicBoolean.new(false)
+          @ready = Concurrent::Event.new
+        end
+
+        def initialized?
+          @initialized.value
+        end
+
+        def start
+          ready = Concurrent::Event.new
+          
+          # We will return immediately regardless of whether the file load succeeded or failed -
+          # the difference can be detected by checking "initialized?"
+          ready.set
+
+          load_all
+
+          if @auto_update
+            # If we're going to watch files, then the start event will be set the first time we get
+            # a successful load.
+            @listener = start_listener
+          end
+
+          ready
+        end
+        
+        def stop
+          @listener.stop if !@listener.nil?
+        end
+
+        private
+
+        def load_all
+          all_data = {
+            FEATURES => {},
+            SEGMENTS => {}
+          }
+          @paths.each do |path|
+            begin
+              load_file(path, all_data)
+            rescue => exn
+              LaunchDarkly::Util.log_exception(@logger, "Unable to load flag data from \"#{path}\"", exn)
+              return
+            end
+          end
+          @feature_store.init(all_data)
+          @initialized.make_true
+        end
+
+        def load_file(path, all_data)
+          parsed = parse_content(IO.read(path))
+          (parsed[:flags] || {}).each do |key, flag|
+            add_item(all_data, FEATURES, flag)
+          end
+          (parsed[:flagValues] || {}).each do |key, value|
+            add_item(all_data, FEATURES, make_flag_with_value(key.to_s, value))
+          end
+          (parsed[:segments] || {}).each do |key, segment|
+            add_item(all_data, SEGMENTS, segment)
+          end
+        end
+
+        def parse_content(content)
+          # We can use the Ruby YAML parser for both YAML and JSON (JSON is a subset of YAML and while
+          # not all YAML parsers handle it correctly, we have verified that the Ruby one does, at least
+          # for all the samples of actual flag data that we've tested).
+          symbolize_all_keys(YAML.safe_load(content))
+        end
+
+        def symbolize_all_keys(value)
+          # This is necessary because YAML.load doesn't have an option for parsing keys as symbols, and
+          # the SDK expects all objects to be formatted that way.
+          if value.is_a?(Hash)
+            value.map{ |k, v| [k.to_sym, symbolize_all_keys(v)] }.to_h
+          elsif value.is_a?(Array)
+            value.map{ |v| symbolize_all_keys(v) }
+          else
+            value
+          end
+        end
+
+        def add_item(all_data, kind, item)
+          items = all_data[kind]
+          raise ArgumentError, "Received unknown item kind #{kind} in add_data" if items.nil? # shouldn't be possible since we preinitialize the hash
+          key = item[:key].to_sym
+          if !items[key].nil?
+            raise ArgumentError, "#{kind[:namespace]} key \"#{item[:key]}\" was used more than once"
+          end
+          items[key] = item
+        end
+
+        def make_flag_with_value(key, value)
+          {
+            key: key,
+            on: true,
+            fallthrough: { variation: 0 },
+            variations: [ value ]
+          }
+        end
+
+        def start_listener
+          resolved_paths = @paths.map { |p| Pathname.new(File.absolute_path(p)).realpath.to_s }
+          if @use_listen
+            start_listener_with_listen_gem(resolved_paths)
+          else
+            FileDataSourcePoller.new(resolved_paths, @poll_interval, self.method(:load_all), @logger)
+          end
+        end
+
+        def start_listener_with_listen_gem(resolved_paths)
+          path_set = resolved_paths.to_set
+          dir_paths = resolved_paths.map{ |p| File.dirname(p) }.uniq
+          opts = { latency: @poll_interval }
+          l = Listen.to(*dir_paths, opts) do |modified, added, removed|
+            paths = modified + added + removed
+            if paths.any? { |p| path_set.include?(p) }
+              load_all
+            end
+          end
+          l.start
+          l
+        end
+
+        #
+        # Used internally by FileDataSource to track data file changes if the 'listen' gem is not available.
+        #
+        class FileDataSourcePoller
+          def initialize(resolved_paths, interval, reloader, logger)
+            @stopped = Concurrent::AtomicBoolean.new(false)
+            get_file_times = Proc.new do
+              ret = {}
+              resolved_paths.each do |path|
+                begin
+                  ret[path] = File.mtime(path)
+                rescue Errno::ENOENT
+                  ret[path] = nil
+                end
+              end
+              ret
+            end
+            last_times = get_file_times.call
+            @thread = Thread.new do
+              while true
+                sleep interval
+                break if @stopped.value
+                begin
+                  new_times = get_file_times.call
+                  changed = false
+                  last_times.each do |path, old_time|
+                    new_time = new_times[path]
+                    if !new_time.nil? && new_time != old_time
+                      changed = true
+                      break
+                    end
+                  end
+                  reloader.call if changed
+                rescue => exn
+                  LaunchDarkly::Util.log_exception(logger, "Unexpected exception in FileDataSourcePoller", exn)
+                end
+              end
+            end
+          end
+
+          def stop
+            @stopped.make_true
+            @thread.run  # wakes it up if it's sleeping
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,10 +5,7 @@ module LaunchDarkly
   module Impl
     module Integrations
       module Redis
-        #
-        # Internal implementation of the Redis feature store, intended to be used with CachingStoreWrapper.
-        #
-        class RedisFeatureStoreCore
+        class RedisStoreImplBase
           begin
             require "redis"
             require "connection_pool"
@@ -19,22 +16,14 @@ module LaunchDarkly
 
           def initialize(opts)
             if !REDIS_ENABLED
-              raise RuntimeError.new("can't use Redis feature store because one of these gems is missing: redis, connection_pool")
+              raise RuntimeError.new("can't use #{description} because one of these gems is missing: redis, connection_pool")
             end
 
-            @redis_opts = opts[:redis_opts] || Hash.new
-            if opts[:redis_url]
-              @redis_opts[:url] = opts[:redis_url]
-            end
-            if !@redis_opts.include?(:url)
-              @redis_opts[:url] = LaunchDarkly::Integrations::Redis::default_redis_url
-            end
-            max_connections = opts[:max_connections] || 16
-            @pool = opts[:pool] || ConnectionPool.new(size: max_connections) do
-              ::Redis.new(@redis_opts)
-            end
+            @pool = create_redis_pool(opts)
+
             # shutdown pool on close unless the client passed a custom pool and specified not to shutdown
             @pool_shutdown_on_close = (!opts[:pool] || opts.fetch(:pool_shutdown_on_close, true))
+
             @prefix = opts[:prefix] || LaunchDarkly::Integrations::Redis::default_prefix
             @logger = opts[:logger] || Config.default_logger
             @test_hook = opts[:test_hook]  # used for unit tests, deliberately undocumented
@@ -42,10 +31,53 @@ module LaunchDarkly
             @stopped = Concurrent::AtomicBoolean.new(false)
 
             with_connection do |redis|
-              @logger.info("RedisFeatureStore: using Redis instance at #{redis.connection[:host]}:#{redis.connection[:port]} \
-      and prefix: #{@prefix}")
+              @logger.info("#{description}: using Redis instance at #{redis.connection[:host]}:#{redis.connection[:port]} and prefix: #{@prefix}")
+            end
+          end
+
+          def stop
+            if @stopped.make_true
+              return unless @pool_shutdown_on_close
+              @pool.shutdown { |redis| redis.close }
+            end
+          end
+
+          protected def description
+            "Redis"
+          end
+
+          protected def with_connection
+            @pool.with { |redis| yield(redis) }
+          end
+
+          private def create_redis_pool(opts)
+            redis_opts = opts[:redis_opts] ? opts[:redis_opts].clone : Hash.new
+            if opts[:redis_url]
+              redis_opts[:url] = opts[:redis_url]
+            end
+            if !redis_opts.include?(:url)
+              redis_opts[:url] = LaunchDarkly::Integrations::Redis::default_redis_url
+            end
+            max_connections = opts[:max_connections] || 16
+            return opts[:pool] || ConnectionPool.new(size: max_connections) do
+              ::Redis.new(redis_opts)
             end
           end
+        end
+
+        #
+        # Internal implementation of the Redis feature store, intended to be used with CachingStoreWrapper.
+        #
+        class RedisFeatureStoreCore < RedisStoreImplBase
+          def initialize(opts)
+            super(opts)
+
+            @test_hook = opts[:test_hook]  # used for unit tests, deliberately undocumented
+          end
+
+          def description
+            "RedisFeatureStore"
+          end
 
           def init_internal(all_data)
             count = 0
@@ -103,8 +135,7 @@ module LaunchDarkly
                   else
                     final_item = old_item
                     action = new_item[:deleted] ? "delete" : "update"
-                    @logger.warn { "RedisFeatureStore: attempted to #{action} #{key} version: #{old_item[:version]} \
-    in '#{kind[:namespace]}' with a version that is the same or older: #{new_item[:version]}" }
+                    @logger.warn { "RedisFeatureStore: attempted to #{action} #{key} version: #{old_item[:version]} in '#{kind[:namespace]}' with a version that is the same or older: #{new_item[:version]}" }
                   end
                   redis.unwatch
                 end
@@ -117,13 +148,6 @@ module LaunchDarkly
             with_connection { |redis| redis.exists?(inited_key) }
           end
 
-          def stop
-            if @stopped.make_true
-              return unless @pool_shutdown_on_close
-              @pool.shutdown { |redis| redis.close }
-            end
-          end
-
           private
 
           def before_update_transaction(base_key, key)
@@ -142,14 +166,43 @@ module LaunchDarkly
             @prefix + ":$inited"
           end
 
-          def with_connection
-            @pool.with { |redis| yield(redis) }
-          end
-
           def get_redis(redis, kind, key)
             Model.deserialize(kind, redis.hget(items_key(kind), key))
           end
         end
+
+        #
+        # Internal implementation of the Redis big segment store.
+        #
+        class RedisBigSegmentStore < RedisStoreImplBase
+          KEY_LAST_UP_TO_DATE = ':big_segments_synchronized_on'
+          KEY_USER_INCLUDE = ':big_segment_include:'
+          KEY_USER_EXCLUDE = ':big_segment_exclude:'
+
+          def description
+            "RedisBigSegmentStore"
+          end
+
+          def get_metadata
+            value = with_connection { |redis| redis.get(@prefix + KEY_LAST_UP_TO_DATE) }
+            Interfaces::BigSegmentStoreMetadata.new(value.nil? ? nil : value.to_i)
+          end
+
+          def get_membership(user_hash)
+            with_connection do |redis|
+              included_refs = redis.smembers(@prefix + KEY_USER_INCLUDE + user_hash)
+              excluded_refs = redis.smembers(@prefix + KEY_USER_EXCLUDE + user_hash)
+              if !included_refs && !excluded_refs
+                nil
+              else
+                membership = {}
+                excluded_refs.each { |ref| membership[ref] = false }
+                included_refs.each { |ref| membership[ref] = true }
+                membership
+              end
+            end
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,40 @@
+require 'concurrent/atomics'
+require 'ldclient-rb/interfaces'
+
+module LaunchDarkly
+  module Impl
+    module Integrations
+      module TestData
+        # @private
+        class TestDataSource
+          include LaunchDarkly::Interfaces::DataSource
+
+          def initialize(feature_store, test_data)
+            @feature_store = feature_store
+            @test_data = test_data
+          end
+
+          def initialized?
+            true
+          end
+
+          def start
+            ready = Concurrent::Event.new
+            ready.set
+            init_data = @test_data.make_init_data
+            @feature_store.init(init_data)
+            ready
+          end
+
+          def stop
+            @test_data.closed_instance(self)
+          end
+
+          def upsert(kind, item)
+            @feature_store.upsert(kind, item)
+          end
+        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

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,6 +3,14 @@ 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
@@ -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