prepare 6.3.0 release

.gitignore

@@ -13,4 +13,5 @@
 mkmf.log
 *.gem
 .DS_Store
-Gemfile.lock
+Gemfile.lock
+.ruby-version

CONTRIBUTING.md

@@ -1,20 +1,16 @@
-Contributing to the LaunchDarkly Server-side SDK for Ruby
-================================================
+# Contributing to the LaunchDarkly Server-side SDK for Ruby
 
 LaunchDarkly has published an [SDK contributor's guide](https://docs.launchdarkly.com/sdk/concepts/contributors-guide) that provides a detailed explanation of how our SDKs work. See below for additional information on how to contribute to this SDK.
 
-Submitting bug reports and feature requests
-------------------
+## Submitting bug reports and feature requests
 
 The LaunchDarkly SDK team monitors the [issue tracker](https://github.com/launchdarkly/ruby-server-sdk/issues) in the SDK repository. Bug reports and feature requests specific to this SDK should be filed in this issue tracker. The SDK team will respond to all newly filed issues within two business days.
 
-Submitting pull requests
-------------------
+## Submitting pull requests
 
 We encourage pull requests and other contributions from the community. Before submitting pull requests, ensure that all temporary or unintended code is removed. Don't worry about adding reviewers to the pull request; the LaunchDarkly SDK team will add themselves. The SDK team will acknowledge all pull requests within two business days.
 
-Build instructions
-------------------
+## Build instructions
 
 ### Prerequisites
 
@@ -35,3 +31,32 @@ bundle exec rspec spec
 ```
 
 By default, the full unit test suite includes live tests of the integrations for Consul, DynamoDB, and Redis. Those tests expect you to have instances of all of those databases running locally. To skip them, set the environment variable `LD_SKIP_DATABASE_TESTS=1` before running the tests.
+
+### Building documentation
+
+Documentation is built automatically with YARD for each release. To build the documentation locally:
+
+```
+cd docs
+make
+```
+
+The output will appear in `docs/build/html`.
+
+## Code organization
+
+The SDK's namespacing convention is as follows:
+
+* `LaunchDarkly`: This namespace contains the most commonly used classes and methods in the SDK, such as `LDClient` and `EvaluationDetail`.
+* `LaunchDarkly::Integrations`: This namespace contains entry points for optional features that are related to how the SDK communicates with other systems, such as `Redis`.
+* `LaunchDarkly::Interfaces`: This namespace contains types that do not do anything by themselves, but may need to be referenced if you are using optional features or implementing a custom component.
+
+A special case is the namespace `LaunchDarkly::Impl`, and any namespaces within it. Everything under `Impl` is considered a private implementation detail: all files there are excluded from the generated documentation, and are considered subject to change at any time and not supported for direct use by application developers. We do this because Ruby's scope/visibility system is somewhat limited compared to other languages: a method can be `private` or `protected` within a class, but there is no way to make it visible to other classes in the SDK yet invisible to code outside of the SDK, and there is similarly no way to hide a class.
+
+So, if there is a class whose existence is entirely an implementation detail, it should be in `Impl`. Similarly, classes that are _not_ in `Impl` must not expose any public members that are not meant to be part of the supported public API. This is important because of our guarantee of backward compatibility for all public APIs within a major version: we want to be able to change our implementation details to suit the needs of the code, without worrying about breaking a customer's code. Due to how the language works, we can't actually prevent an application developer from referencing those classes in their code, but this convention makes it clear that such use is discouraged and unsupported.
+
+## Documenting types and methods
+
+All classes and public methods outside of `LaunchDarkly::Impl` should have documentation comments. These are used to build the API documentation that is published at https://launchdarkly.github.io/ruby-server-sdk/ and https://www.rubydoc.info/gems/launchdarkly-server-sdk. The documentation generator is YARD; see https://yardoc.org/ for the comment format it uses.
+
+Please try to make the style and terminology in documentation comments consistent with other documentation comments in the SDK. Also, if a class or method is being added that has an equivalent in other SDKs, and if we have described it in a consistent away in those other SDKs, please reuse the text whenever possible (with adjustments for anything language-specific) rather than writing new text.

lib/ldclient-rb/config.rb

@@ -42,6 +42,7 @@ class Config
     # @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 @@ def initialize(opts = {})
       @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 @@ def offline?
     # 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 @@ def self.minimum_diagnostic_recording_interval
       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

lib/ldclient-rb/evaluation_detail.rb

@@ -110,27 +110,42 @@ class EvaluationReason
 
     # 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 @@ def self.error(error_kind)
     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 @@ def as_json(*) # parameter is unused, but may be passed if we're using the json
       # 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 @@ def as_json(*) # parameter is unused, but may be passed if we're using the json
       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 @@ def [](key)
         @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 @@ def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_exper
       @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 @@ def self.make_error(error_kind)
       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