launchdarkly-server-sdk 6.2.5 → 6.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f1b216e5ae2518b79aae9613ecd04b02ed525ea2d25084df805eae7d92cb219
-  data.tar.gz: 317db7e14a292968b245e39e3cd4be33206fd8085c8ebd04be43f1c987434228
+  metadata.gz: '01240358ce506d6913d6111e3683b72b63c303601c4b02987227a94b64cea9fa'
+  data.tar.gz: dcd7ed0b5a4f94db862a6a3ff77b098ce450335088d286fc48b50b85cf923831
 SHA512:
-  metadata.gz: 5d9182ccde6530f67df30fd8a238e9b510e89dc235cf76c45140cb6eaa36b8e342a44a98595b8c86f171c8f6f1cc74291f3c2ebf11ac274f2a1e46d64798318c
-  data.tar.gz: 4b54fc711795c06e3bdabb9dd593af8499aa8e8c28eec1f9db508a5a6c5288cd0268b7ce9d324c892425ffcf080f0ad21e78060a74e0186f19998bd40f076943
+  metadata.gz: 2ca40956187c82f7427f5fa520972a90c905da18a2442745a061e0892a7b8038333d9209418e66dda6ea00d39213420ebc4b5a0b3850a8f05558ba1fdaaac37d
+  data.tar.gz: '04119f2473332cc4cd79d34c2c0937adaf54398eba17a2de28e322530943e333ffd64bc42f55bba40cc1aa77ff6c763b373ec18f0a6351bb36073737d926d8dd'

data/lib/ldclient-rb/config.rb

@@ -42,6 +42,7 @@ module LaunchDarkly
     # @option opts [String] :wrapper_name See {#wrapper_name}.
     # @option opts [String] :wrapper_version See {#wrapper_version}.
     # @option opts [#open] :socket_factory See {#socket_factory}.
+    # @option opts [BigSegmentsConfig] :big_segments See {#big_segments}.
     #
     def initialize(opts = {})
       @base_uri = (opts[:base_uri] || Config.default_base_uri).chomp("/")
@@ -73,6 +74,7 @@ module LaunchDarkly
       @wrapper_name = opts[:wrapper_name]
       @wrapper_version = opts[:wrapper_version]
       @socket_factory = opts[:socket_factory]
+      @big_segments = opts[:big_segments] || BigSegmentsConfig.new(store: nil)
     end
 
     #
@@ -258,10 +260,21 @@ module LaunchDarkly
     # object.
     #
     # @return [LaunchDarkly::Interfaces::DataSource|lambda]
-    # @see FileDataSource
+    # @see LaunchDarkly::Integrations::FileData
+    # @see LaunchDarkly::Integrations::TestData
     #
     attr_reader :data_source
 
+    #
+    # Configuration options related to Big Segments.
+    #
+    # Big Segments are a specific type of user segments. For more information, read the LaunchDarkly
+    # documentation: https://docs.launchdarkly.com/home/users/big-segments
+    #
+    # @return [BigSegmentsConfig]
+    #
+    attr_reader :big_segments
+
     # @deprecated This is replaced by {#data_source}.
     attr_reader :update_processor
     
@@ -484,4 +497,68 @@ module LaunchDarkly
       60
     end
   end
+
+  #
+  # Configuration options related to Big Segments.
+  #
+  # Big Segments are a specific type of user segments. For more information, read the LaunchDarkly
+  # documentation: https://docs.launchdarkly.com/home/users/big-segments
+  #
+  # If your application uses Big Segments, you will need to create a `BigSegmentsConfig` that at a
+  # minimum specifies what database integration to use, and then pass the `BigSegmentsConfig`
+  # object as the `big_segments` parameter when creating a {Config}.
+  #
+  # @example Configuring Big Segments with Redis
+  #     store = LaunchDarkly::Integrations::Redis::new_big_segments_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)
+  #
+  class BigSegmentsConfig
+    DEFAULT_USER_CACHE_SIZE = 1000
+    DEFAULT_USER_CACHE_TIME = 5
+    DEFAULT_STATUS_POLL_INTERVAL = 5
+    DEFAULT_STALE_AFTER = 2 * 60
+
+    #
+    # Constructor for setting Big Segments options.
+    #
+    # @param store [LaunchDarkly::Interfaces::BigSegmentStore] the data store implementation
+    # @param user_cache_size [Integer] See {#user_cache_size}.
+    # @param user_cache_time [Float] See {#user_cache_time}.
+    # @param status_poll_interval [Float] See {#status_poll_interval}.
+    # @param stale_after [Float] See {#stale_after}.
+    #
+    def initialize(store:, user_cache_size: nil, user_cache_time: nil, status_poll_interval: nil, stale_after: nil)
+      @store = store
+      @user_cache_size = user_cache_size.nil? ? DEFAULT_USER_CACHE_SIZE : user_cache_size
+      @user_cache_time = user_cache_time.nil? ? DEFAULT_USER_CACHE_TIME : user_cache_time
+      @status_poll_interval = status_poll_interval.nil? ? DEFAULT_STATUS_POLL_INTERVAL : status_poll_interval
+      @stale_after = stale_after.nil? ? DEFAULT_STALE_AFTER : stale_after
+    end
+
+    # The implementation of {LaunchDarkly::Interfaces::BigSegmentStore} that will be used to
+    # query the Big Segments database.
+    # @return [LaunchDarkly::Interfaces::BigSegmentStore]
+    attr_reader :store
+
+    # The maximum number of users whose Big Segment state will be cached by the SDK at any given time.
+    # @return [Integer]
+    attr_reader :user_cache_size
+
+    # The maximum length of time (in seconds) that the Big Segment state for a user will be cached
+    # by the SDK.
+    # @return [Float]
+    attr_reader :user_cache_time
+
+    # The interval (in seconds) at which the SDK will poll the Big Segment store to make sure it is
+    # available and to determine how long ago it was updated.
+    # @return [Float]
+    attr_reader :status_poll_interval
+
+    # The maximum length of time between updates of the Big Segments data before the data is
+    # considered out of date.
+    # @return [Float]
+    attr_reader :stale_after
+  end
 end

data/lib/ldclient-rb/evaluation_detail.rb

@@ -110,27 +110,42 @@ module LaunchDarkly
 
     # Indicates the general category of the reason. Will always be one of the class constants such
     # as {#OFF}.
+    # @return [Symbol]
     attr_reader :kind
 
     # The index of the rule that was matched (0 for the first rule in the feature flag). If
     # {#kind} is not {#RULE_MATCH}, this will be `nil`.
+    # @return [Integer|nil]
     attr_reader :rule_index
 
     # A unique string identifier for the matched rule, which will not change if other rules are added
     # or deleted. If {#kind} is not {#RULE_MATCH}, this will be `nil`.
+    # @return [String]
     attr_reader :rule_id
 
     # A boolean or nil value representing if the rule or fallthrough has an experiment rollout.
+    # @return [Boolean|nil]
     attr_reader :in_experiment
 
     # The key of the prerequisite flag that did not return the desired variation. If {#kind} is not
     # {#PREREQUISITE_FAILED}, this will be `nil`.
+    # @return [String]
     attr_reader :prerequisite_key
 
     # A value indicating the general category of error. This should be one of the class constants such
     # as {#ERROR_FLAG_NOT_FOUND}. If {#kind} is not {#ERROR}, it will be `nil`.
+    # @return [Symbol]
     attr_reader :error_kind
 
+    # Describes the validity of Big Segment information, if and only if the flag evaluation required
+    # 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
+    # documentation: https://docs.launchdarkly.com/home/users/big-segments
+    # @return [Symbol]
+    attr_reader :big_segments_status
+
     # Returns an instance whose {#kind} is {#OFF}.
     # @return [EvaluationReason]
     def self.off
@@ -196,11 +211,13 @@ module LaunchDarkly
     def ==(other)
       if other.is_a? EvaluationReason
         @kind == other.kind && @rule_index == other.rule_index && @rule_id == other.rule_id &&
-          @prerequisite_key == other.prerequisite_key && @error_kind == other.error_kind
+          @prerequisite_key == other.prerequisite_key && @error_kind == other.error_kind &&
+          @big_segments_status == other.big_segments_status
       elsif other.is_a? Hash
         @kind.to_s == other[:kind] && @rule_index == other[:ruleIndex] && @rule_id == other[:ruleId] &&
           @prerequisite_key == other[:prerequisiteKey] &&
-          (other[:errorKind] == @error_kind.nil? ? nil : @error_kind.to_s)
+          (other[:errorKind] == @error_kind.nil? ? nil : @error_kind.to_s) &&
+          (other[:bigSegmentsStatus] == @big_segments_status.nil? ? nil : @big_segments_status.to_s)
       end
     end
 
@@ -242,7 +259,7 @@ module LaunchDarkly
       # enabled for a flag and the application called variation_detail, or 2. experimentation is
       # enabled for an evaluation. We can't reuse these hashes because an application could call
       # as_json and then modify the result.
-      case @kind
+      ret = case @kind
       when :RULE_MATCH
         if @in_experiment
           { kind: @kind, ruleIndex: @rule_index, ruleId: @rule_id, inExperiment: @in_experiment }
@@ -262,6 +279,10 @@ module LaunchDarkly
       else
         { kind: @kind }
       end
+      if !@big_segments_status.nil?
+        ret[:bigSegmentsStatus] = @big_segments_status
+      end
+      ret
     end
 
     # Same as {#as_json}, but converts the JSON structure into a string.
@@ -285,14 +306,24 @@ module LaunchDarkly
         @prerequisite_key
       when :errorKind
         @error_kind.nil? ? nil : @error_kind.to_s
+      when :bigSegmentsStatus
+        @big_segments_status.nil? ? nil : @big_segments_status.to_s
       else
         nil
       end
     end
 
-    private
+    def with_big_segments_status(big_segments_status)
+      return self if @big_segments_status == big_segments_status
+      EvaluationReason.new(@kind, @rule_index, @rule_id, @prerequisite_key, @error_kind, @in_experiment, big_segments_status)
+    end
 
-    def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment=nil)
+    #
+    # Constructor that sets all properties. Applications should not normally use this constructor,
+    # but should use class methods like {#off} to avoid creating unnecessary instances.
+    #
+    def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment=nil,
+        big_segments_status = nil)
       @kind = kind.to_sym
       @rule_index = rule_index
       @rule_id = rule_id
@@ -301,11 +332,10 @@ module LaunchDarkly
       @prerequisite_key.freeze if !prerequisite_key.nil?
       @error_kind = error_kind
       @in_experiment = in_experiment
+      @big_segments_status = big_segments_status
     end
 
-    private_class_method :new
-
-    def self.make_error(error_kind)
+    private_class_method def self.make_error(error_kind)
       new(:ERROR, nil, nil, nil, error_kind)
     end
 
@@ -321,4 +351,33 @@ module LaunchDarkly
       ERROR_EXCEPTION => make_error(ERROR_EXCEPTION)
     }
   end
+
+  #
+  # Defines the possible values of {EvaluationReason#big_segments_status}.
+  #
+  module BigSegmentsStatus
+    #
+    # Indicates that the Big Segment query involved in the flag evaluation was successful, and
+    # that the segment state is considered up to date.
+    #
+    HEALTHY = :HEALTHY
+
+    #
+    # Indicates that the Big Segment query involved in the flag evaluation was successful, but
+    # that the segment state may not be up to date.
+    #
+    STALE = :STALE
+
+    #
+    # Indicates that Big Segments could not be queried for the flag evaluation because the SDK
+    # configuration did not include a Big Segment store.
+    #
+    NOT_CONFIGURED = :NOT_CONFIGURED
+
+    #
+    # Indicates that the Big Segment query involved in the flag evaluation failed, for instance
+    # due to a database error.
+    #
+    STORE_ERROR = :STORE_ERROR
+  end
 end

data/lib/ldclient-rb/file_data_source.rb

@@ -1,314 +1,23 @@
-require 'concurrent/atomics'
-require 'json'
-require 'yaml'
-require 'pathname'
+require "ldclient-rb/integrations/file_data"
 
 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
-
-  #
-  # 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 {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):
-  #
-  #     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?}.
-  #
-  # 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):
+  # Deprecated entry point for the file data source feature.
   #
-  #     {
-  #       "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" ]
-  #         }
-  #       }
-  #     }
+  # The new preferred usage is {LaunchDarkly::Integrations::FileData#data_source}.
   #
-  # 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.      
+  # @deprecated This is replaced by {LaunchDarkly::Integrations::FileData}.
   #
   class FileDataSource
     #
-    # 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}
+    # Deprecated entry point for the file data source feature.
     #
-    def self.factory(options={})
-      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
-      @logger = logger
-      @paths = options[:paths] || []
-      if @paths.is_a? String
-        @paths = [ @paths ]
-      end
-      @auto_update = options[:auto_update]
-      if @auto_update && LaunchDarkly.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
-          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
-
+    # The new preferred usage is {LaunchDarkly::Integrations::FileData#data_source}.
     #
-    # Used internally by FileDataSource to track data file changes if the 'listen' gem is not available.
+    # @deprecated This is replaced by {LaunchDarkly::Integrations::FileData#data_source}.
     #
-    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
-              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
+    def self.factory(options={})
+      LaunchDarkly::Integrations::FileData.data_source(options)
     end
   end
 end