launchdarkly-server-sdk 5.7.3 → 6.0.0

data/README.md

@@ -5,6 +5,8 @@ LaunchDarkly Server-side SDK for Ruby
 
 [![Circle CI](https://circleci.com/gh/launchdarkly/ruby-server-sdk/tree/master.svg?style=svg)](https://circleci.com/gh/launchdarkly/ruby-server-sdk/tree/master)
 [![Security](https://hakiri.io/github/launchdarkly/ruby-server-sdk/master.svg)](https://hakiri.io/github/launchdarkly/ruby-server-sdk/master)
+[![RubyDoc](https://img.shields.io/static/v1?label=docs+-+all+versions&message=reference&color=00add8)](https://www.rubydoc.info/gems/launchdarkly-server-sdk)
+[![GitHub Pages](https://img.shields.io/static/v1?label=docs+-+latest&message=reference&color=00add8)](https://launchdarkly.github.io/ruby-server-sdk)
 
 LaunchDarkly overview
 -------------------------
@@ -15,7 +17,7 @@ LaunchDarkly overview
 Supported Ruby versions
 -----------------------
 
-This version of the LaunchDarkly SDK has a minimum Ruby version of 2.2.6, or 9.1.6 for JRuby.
+This version of the LaunchDarkly SDK has a minimum Ruby version of 2.5.0, or 9.2.0 for JRuby.
 
 Getting started
 -----------
@@ -27,7 +29,7 @@ Learn more
 
 Check out our [documentation](http://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [reference guide for this SDK](http://docs.launchdarkly.com/docs/ruby-sdk-reference).
 
-Generated API documentation is on [RubyDoc.info](https://www.rubydoc.info/gems/launchdarkly-server-sdk).
+Generated API documentation for all versions of the SDK is on [RubyDoc.info](https://www.rubydoc.info/gems/launchdarkly-server-sdk). The API documentation for the latest version is also on [GitHub Pages](https://launchdarkly.github.io/ruby-server-sdk).
 
 Testing
 -------
@@ -53,4 +55,4 @@ About LaunchDarkly
     * [docs.launchdarkly.com](https://docs.launchdarkly.com/  "LaunchDarkly Documentation") for our documentation and SDK reference guides
     * [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/  "LaunchDarkly API Documentation") for our API documentation
     * [blog.launchdarkly.com](https://blog.launchdarkly.com/  "LaunchDarkly Blog Documentation") for the latest product updates
-    * [Feature Flagging Guide](https://github.com/launchdarkly/featureflags/  "Feature Flagging Guide") for best practices and strategies
+    * [Feature Flagging Guide](https://github.com/launchdarkly/featureflags/  "Feature Flagging Guide") for best practices and strategies

data/azure-pipelines.yml

@@ -45,7 +45,7 @@ jobs:
           workingDirectory: $(System.DefaultWorkingDirectory)
           script: |
             ruby -v
-            gem install bundler -v 1.17.3
+            gem install bundler
             bundle install
             mkdir rspec
             bundle exec rspec --format progress --format RspecJunitFormatter -o ./rspec/rspec.xml spec

data/docs/Makefile

@@ -0,0 +1,26 @@
+
+ifeq ($(LD_RELEASE_VERSION),)
+TITLE=LaunchDarkly Ruby SDK
+else
+TITLE=LaunchDarkly Ruby SDK ($(LD_RELEASE_VERSION))
+endif
+
+.PHONY: dependencies html
+
+html: dependencies
+	rm -rf ./build
+	cd .. && yard doc \
+		-o docs/build/html \
+		--title "$(TITLE)" \
+		--no-private \
+		--markup markdown \
+		--embed-mixins \
+		-r docs/index.md \
+		lib/*.rb \
+		lib/**/*.rb \
+		lib/**/**/*.rb \
+		lib/**/**/**/*.rb
+
+dependencies:
+	gem install --conservative yard
+	gem install --conservative redcarpet  # provides Markdown formatting

data/docs/index.md

@@ -0,0 +1,9 @@
+# LaunchDarkly Server-side SDK for Ruby
+
+This generated API documentation lists all types and methods in the SDK.
+
+The API documentation for the most recent SDK release is hosted on [GitHub Pages](https://launchdarkly.github.io/ruby-server-sdk). API documentation for current and past releases is hosted on [RubyDoc.info](https://www.rubydoc.info/gems/launchdarkly-server-sdk).
+
+Source code and readme: [GitHub](https://github.com/launchdarkly/ruby-server-sdk)
+
+SDK reference guide: [docs.launchdarkly.com](https://docs.launchdarkly.com/sdk/server-side/ruby)

data/launchdarkly-server-sdk.gemspec

@@ -19,20 +19,27 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
+  spec.required_ruby_version = ">= 2.5.0"
 
-  spec.add_development_dependency "aws-sdk-dynamodb", "~> 1.18"
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rspec", "~> 3.2"
-  spec.add_development_dependency "codeclimate-test-reporter", "~> 0"
-  spec.add_development_dependency "diplomat", ">= 2.0.2"
-  spec.add_development_dependency "redis", "~> 3.3.5"
-  spec.add_development_dependency "connection_pool", ">= 2.1.2"
-  spec.add_development_dependency "rspec_junit_formatter", "~> 0.3.0"
-  spec.add_development_dependency "timecop", "~> 0.9.1"
-  spec.add_development_dependency "listen", "~> 3.0" # see file_data_source.rb
+  spec.add_development_dependency "aws-sdk-dynamodb", "~> 1.57"
+  spec.add_development_dependency "bundler", "~> 2.1"
+  spec.add_development_dependency "rspec", "~> 3.10"
+  spec.add_development_dependency "diplomat", "~> 2.4.2"
+  spec.add_development_dependency "redis", "~> 4.2"
+  spec.add_development_dependency "connection_pool", "~> 2.2.3"
+  spec.add_development_dependency "rspec_junit_formatter", "~> 0.4"
+  spec.add_development_dependency "timecop", "~> 0.9"
+  spec.add_development_dependency "listen", "~> 3.3" # see file_data_source.rb
+  spec.add_development_dependency "webrick", "~> 1.7"
+  # required by dynamodb
+  spec.add_development_dependency "oga", "~> 2.2"
 
-  spec.add_runtime_dependency "json", [">= 1.8", "< 3"]
   spec.add_runtime_dependency "semantic", "~> 1.6"
-  spec.add_runtime_dependency "concurrent-ruby", "~> 1.0"
-  spec.add_runtime_dependency "ld-eventsource", "1.0.3"
+  spec.add_runtime_dependency "concurrent-ruby", "~> 1.1"
+  spec.add_runtime_dependency "ld-eventsource", "~> 2.0"
+
+  # lock json to 2.3.x as ruby libraries often remove
+  # support for older ruby versions in minor releases
+  spec.add_runtime_dependency "json", "~> 2.3.1"
+  spec.add_runtime_dependency "http", "~> 4.4.1"
 end

data/lib/ldclient-rb.rb

@@ -8,7 +8,6 @@ end
 require "ldclient-rb/version"
 require "ldclient-rb/interfaces"
 require "ldclient-rb/util"
-require "ldclient-rb/evaluation"
 require "ldclient-rb/flags_state"
 require "ldclient-rb/ldclient"
 require "ldclient-rb/cache_store"

data/lib/ldclient-rb/config.rb

@@ -15,7 +15,7 @@ module LaunchDarkly
     #
     # @param opts [Hash] the configuration options
     # @option opts [Logger] :logger See {#logger}.
-    # @option opts [String] :base_uri ("https://app.launchdarkly.com") See {#base_uri}.
+    # @option opts [String] :base_uri ("https://sdk.launchdarkly.com") See {#base_uri}.
     # @option opts [String] :stream_uri ("https://stream.launchdarkly.com") See {#stream_uri}.
     # @option opts [String] :events_uri ("https://events.launchdarkly.com") See {#events_uri}.
     # @option opts [Integer] :capacity (10000) See {#capacity}.
@@ -41,6 +41,7 @@ module LaunchDarkly
     # @option opts [Float] :diagnostic_recording_interval (900) See {#diagnostic_recording_interval}.
     # @option opts [String] :wrapper_name See {#wrapper_name}.
     # @option opts [String] :wrapper_version See {#wrapper_version}.
+    # @option opts [#open] :socket_factory See {#socket_factory}.
     #
     def initialize(opts = {})
       @base_uri = (opts[:base_uri] || Config.default_base_uri).chomp("/")
@@ -71,6 +72,7 @@ module LaunchDarkly
         opts[:diagnostic_recording_interval] : Config.default_diagnostic_recording_interval
       @wrapper_name = opts[:wrapper_name]
       @wrapper_version = opts[:wrapper_version]
+      @socket_factory = opts[:socket_factory]
     end
 
     #
@@ -305,6 +307,16 @@ module LaunchDarkly
     #
     attr_reader :wrapper_version
 
+    #
+    # The factory used to construct sockets for HTTP operations. The factory must
+    # provide the method `open(uri, timeout)`. The `open` method must return a
+    # connected stream that implements the `IO` class, such as a `TCPSocket`.
+    #
+    # Defaults to nil.
+    # @return [#open]
+    #
+    attr_reader :socket_factory
+
     #
     # The default LaunchDarkly client configuration. This configuration sets
     # reasonable defaults for most users.
@@ -324,10 +336,10 @@ module LaunchDarkly
 
     #
     # The default value for {#base_uri}.
-    # @return [String] "https://app.launchdarkly.com"
+    # @return [String] "https://sdk.launchdarkly.com"
     #
     def self.default_base_uri
-      "https://app.launchdarkly.com"
+      "https://sdk.launchdarkly.com"
     end
 
     #

data/lib/ldclient-rb/evaluation_detail.rb

@@ -0,0 +1,293 @@
+
+module LaunchDarkly
+# An object returned by {LDClient#variation_detail}, combining the result of a flag evaluation with
+  # an explanation of how it was calculated.
+  class EvaluationDetail
+    # Creates a new instance.
+    #
+    # @param value the result value of the flag evaluation; may be of any type
+    # @param variation_index [int|nil] the index of the value within the flag's list of variations, or
+    #  `nil` if the application default value was returned
+    # @param reason [EvaluationReason] an object describing the main factor that influenced the result
+    # @raise [ArgumentError] if `variation_index` or `reason` is not of the correct type
+    def initialize(value, variation_index, reason)
+      raise ArgumentError.new("variation_index must be a number") if !variation_index.nil? && !(variation_index.is_a? Numeric)
+      raise ArgumentError.new("reason must be an EvaluationReason") if !(reason.is_a? EvaluationReason)
+      @value = value
+      @variation_index = variation_index
+      @reason = reason
+    end
+
+    #
+    # The result of the flag evaluation. This will be either one of the flag's variations, or the
+    # default value that was passed to {LDClient#variation_detail}. It is the same as the return
+    # value of {LDClient#variation}.
+    #
+    # @return [Object]
+    #
+    attr_reader :value
+
+    #
+    # The index of the returned value within the flag's list of variations. The first variation is
+    # 0, the second is 1, etc. This is `nil` if the default value was returned.
+    #
+    # @return [int|nil]
+    #
+    attr_reader :variation_index
+
+    #
+    # An object describing the main factor that influenced the flag evaluation value.
+    #
+    # @return [EvaluationReason]
+    #
+    attr_reader :reason
+
+    #
+    # Tests whether the flag evaluation returned a default value. This is the same as checking
+    # whether {#variation_index} is nil.
+    #
+    # @return [Boolean]
+    #
+    def default_value?
+      variation_index.nil?
+    end
+
+    def ==(other)
+      @value == other.value && @variation_index == other.variation_index && @reason == other.reason
+    end
+  end
+
+  # Describes the reason that a flag evaluation produced a particular value. This is returned by
+  # methods such as {LDClient#variation_detail} as the `reason` property of an {EvaluationDetail}.
+  #
+  # The `kind` property is always defined, but other properties will have non-nil values only for
+  # certain values of `kind`. All properties are immutable.
+  #
+  # There is a standard JSON representation of evaluation reasons when they appear in analytics events.
+  # Use `as_json` or `to_json` to convert to this representation.
+  #
+  # Use factory methods such as {EvaluationReason#off} to obtain instances of this class.
+  class EvaluationReason
+    # Value for {#kind} indicating that the flag was off and therefore returned its configured off value.
+    OFF = :OFF
+    
+    # Value for {#kind} indicating that the flag was on but the user did not match any targets or rules.
+    FALLTHROUGH = :FALLTHROUGH
+    
+    # Value for {#kind} indicating that the user key was specifically targeted for this flag.
+    TARGET_MATCH = :TARGET_MATCH
+    
+    # Value for {#kind} indicating that the user matched one of the flag's rules.
+    RULE_MATCH = :RULE_MATCH
+    
+    # Value for {#kind} indicating that the flag was considered off because it had at least one
+    # prerequisite flag that either was off or did not return the desired variation.
+    PREREQUISITE_FAILED = :PREREQUISITE_FAILED
+    
+    # Value for {#kind} indicating that the flag could not be evaluated, e.g. because it does not exist
+    # or due to an unexpected error. In this case the result value will be the application default value
+    # that the caller passed to the client. Check {#error_kind} for more details on the problem.
+    ERROR = :ERROR
+
+    # Value for {#error_kind} indicating that the caller tried to evaluate a flag before the client had
+    # successfully initialized.
+    ERROR_CLIENT_NOT_READY = :CLIENT_NOT_READY
+
+    # Value for {#error_kind} indicating that the caller provided a flag key that did not match any known flag.
+    ERROR_FLAG_NOT_FOUND = :FLAG_NOT_FOUND
+
+    # Value for {#error_kind} indicating that there was an internal inconsistency in the flag data, e.g.
+    # a rule specified a nonexistent  variation. An error message will always be logged in this case.
+    ERROR_MALFORMED_FLAG = :MALFORMED_FLAG
+
+    # Value for {#error_kind} indicating that the caller passed `nil` for the user parameter, or the
+    # user lacked a key.
+    ERROR_USER_NOT_SPECIFIED = :USER_NOT_SPECIFIED
+
+    # Value for {#error_kind} indicating that an unexpected exception stopped flag evaluation. An error
+    # message will always be logged in this case.
+    ERROR_EXCEPTION = :EXCEPTION
+
+    # Indicates the general category of the reason. Will always be one of the class constants such
+    # as {#OFF}.
+    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`.
+    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`.
+    attr_reader :rule_id
+
+    # The key of the prerequisite flag that did not return the desired variation. If {#kind} is not
+    # {#PREREQUISITE_FAILED}, this will be `nil`.
+    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`.
+    attr_reader :error_kind
+
+    # Returns an instance whose {#kind} is {#OFF}.
+    # @return [EvaluationReason]
+    def self.off
+      @@off
+    end
+
+    # Returns an instance whose {#kind} is {#FALLTHROUGH}.
+    # @return [EvaluationReason]
+    def self.fallthrough
+      @@fallthrough
+    end
+
+    # Returns an instance whose {#kind} is {#TARGET_MATCH}.
+    # @return [EvaluationReason]
+    def self.target_match
+      @@target_match
+    end
+
+    # Returns an instance whose {#kind} is {#RULE_MATCH}.
+    #
+    # @param rule_index [Number] the index of the rule that was matched (0 for the first rule in
+    #   the feature flag)
+    # @param rule_id [String] unique string identifier for the matched rule
+    # @return [EvaluationReason]
+    # @raise [ArgumentError] if `rule_index` is not a number or `rule_id` is not a string
+    def self.rule_match(rule_index, rule_id)
+      raise ArgumentError.new("rule_index must be a number") if !(rule_index.is_a? Numeric)
+      raise ArgumentError.new("rule_id must be a string") if !rule_id.nil? && !(rule_id.is_a? String) # in test data, ID could be nil
+      new(:RULE_MATCH, rule_index, rule_id, nil, nil)
+    end
+
+    # Returns an instance whose {#kind} is {#PREREQUISITE_FAILED}.
+    #
+    # @param prerequisite_key [String] key of the prerequisite flag that did not return the desired variation
+    # @return [EvaluationReason]
+    # @raise [ArgumentError] if `prerequisite_key` is nil or not a string
+    def self.prerequisite_failed(prerequisite_key)
+      raise ArgumentError.new("prerequisite_key must be a string") if !(prerequisite_key.is_a? String)
+      new(:PREREQUISITE_FAILED, nil, nil, prerequisite_key, nil)
+    end
+
+    # Returns an instance whose {#kind} is {#ERROR}.
+    #
+    # @param error_kind [Symbol] value indicating the general category of error
+    # @return [EvaluationReason]
+    # @raise [ArgumentError] if `error_kind` is not a symbol
+    def self.error(error_kind)
+      raise ArgumentError.new("error_kind must be a symbol") if !(error_kind.is_a? Symbol)
+      e = @@error_instances[error_kind]
+      e.nil? ? make_error(error_kind) : e
+    end
+
+    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
+      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)
+      end
+    end
+
+    # Equivalent to {#inspect}.
+    # @return [String]
+    def to_s
+      inspect
+    end
+
+    # Returns a concise string representation of the reason. Examples: `"FALLTHROUGH"`,
+    # `"ERROR(FLAG_NOT_FOUND)"`. The exact syntax is not guaranteed to remain the same; this is meant
+    # for debugging.
+    # @return [String]
+    def inspect
+      case @kind
+      when :RULE_MATCH
+        "RULE_MATCH(#{@rule_index},#{@rule_id})"
+      when :PREREQUISITE_FAILED
+        "PREREQUISITE_FAILED(#{@prerequisite_key})"
+      when :ERROR
+        "ERROR(#{@error_kind})"
+      else
+        @kind.to_s
+      end
+    end
+
+    # Returns a hash that can be used as a JSON representation of the reason, in the format used
+    # in LaunchDarkly analytics events.
+    # @return [Hash]
+    def as_json(*) # parameter is unused, but may be passed if we're using the json gem
+      # Note that this implementation is somewhat inefficient; it allocates a new hash every time.
+      # However, in normal usage the SDK only serializes reasons if 1. full event tracking is
+      # 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
+      when :RULE_MATCH
+        { kind: @kind, ruleIndex: @rule_index, ruleId: @rule_id }
+      when :PREREQUISITE_FAILED
+        { kind: @kind, prerequisiteKey: @prerequisite_key }
+      when :ERROR
+        { kind: @kind, errorKind: @error_kind }
+      else
+        { kind: @kind }
+      end
+    end
+
+    # Same as {#as_json}, but converts the JSON structure into a string.
+    # @return [String]
+    def to_json(*a)
+      as_json.to_json(a)
+    end
+
+    # Allows this object to be treated as a hash corresponding to its JSON representation. For
+    # instance, if `reason.kind` is {#RULE_MATCH}, then `reason[:kind]` will be `"RULE_MATCH"` and
+    # `reason[:ruleIndex]` will be equal to `reason.rule_index`.
+    def [](key)
+      case key
+      when :kind
+        @kind.to_s
+      when :ruleIndex
+        @rule_index
+      when :ruleId
+        @rule_id
+      when :prerequisiteKey
+        @prerequisite_key
+      when :errorKind
+        @error_kind.nil? ? nil : @error_kind.to_s
+      else
+        nil
+      end
+    end
+
+    private
+
+    def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind)
+      @kind = kind.to_sym
+      @rule_index = rule_index
+      @rule_id = rule_id
+      @rule_id.freeze if !rule_id.nil?
+      @prerequisite_key = prerequisite_key
+      @prerequisite_key.freeze if !prerequisite_key.nil?
+      @error_kind = error_kind
+    end
+
+    private_class_method :new
+
+    def self.make_error(error_kind)
+      new(:ERROR, nil, nil, nil, error_kind)
+    end
+
+    @@fallthrough = new(:FALLTHROUGH, nil, nil, nil, nil)
+    @@off = new(:OFF, nil, nil, nil, nil)
+    @@target_match = new(:TARGET_MATCH, nil, nil, nil, nil)
+    @@error_instances = {
+      ERROR_CLIENT_NOT_READY => make_error(ERROR_CLIENT_NOT_READY),
+      ERROR_FLAG_NOT_FOUND => make_error(ERROR_FLAG_NOT_FOUND),
+      ERROR_MALFORMED_FLAG => make_error(ERROR_MALFORMED_FLAG),
+      ERROR_USER_NOT_SPECIFIED => make_error(ERROR_USER_NOT_SPECIFIED),
+      ERROR_EXCEPTION => make_error(ERROR_EXCEPTION)
+    }
+  end
+end