launchdarkly-server-sdk 6.3.0 → 8.0.0

data/lib/ldclient-rb/migrations.rb

@@ -0,0 +1,230 @@
+require 'ldclient-rb/impl/migrations/migrator'
+
+module LaunchDarkly
+  #
+  # Namespace for feature-flag based technology migration support.
+  #
+  module Migrations
+    # Symbol representing the old origin, or the old technology source you are migrating away from.
+    ORIGIN_OLD = :old
+    # Symbol representing the new origin, or the new technology source you are migrating towards.
+    ORIGIN_NEW = :new
+
+    # Symbol defining a read-related operation
+    OP_READ = :read
+    # Symbol defining a write-related operation
+    OP_WRITE = :write
+
+    STAGE_OFF = :off
+    STAGE_DUALWRITE = :dualwrite
+    STAGE_SHADOW = :shadow
+    STAGE_LIVE = :live
+    STAGE_RAMPDOWN = :rampdown
+    STAGE_COMPLETE = :complete
+
+    VALID_OPERATIONS = [
+      OP_READ,
+      OP_WRITE,
+    ]
+
+    VALID_ORIGINS = [
+      ORIGIN_OLD,
+      ORIGIN_NEW,
+    ]
+
+    VALID_STAGES = [
+      STAGE_OFF,
+      STAGE_DUALWRITE,
+      STAGE_SHADOW,
+      STAGE_LIVE,
+      STAGE_RAMPDOWN,
+      STAGE_COMPLETE,
+    ]
+
+    #
+    # The OperationResult wraps the {LaunchDarkly::Result} class to tie an operation origin to a result.
+    #
+    class OperationResult
+      extend Forwardable
+      def_delegators :@result, :value, :error, :exception, :success?
+
+      #
+      # @param origin [Symbol]
+      # @param result [LaunchDarkly::Result]
+      #
+      def initialize(origin, result)
+        @origin = origin
+        @result = result
+      end
+
+      #
+      # @return [Symbol] The origin this result is associated with.
+      #
+      attr_reader :origin
+    end
+
+    #
+    # A write result contains the operation results against both the authoritative and non-authoritative origins.
+    #
+    # Authoritative writes are always executed first. In the event of a failure, the non-authoritative write will not
+    # be executed, resulting in a nil value in the final WriteResult.
+    #
+    class WriteResult
+      #
+      # @param authoritative [OperationResult]
+      # @param nonauthoritative [OperationResult, nil]
+      #
+      def initialize(authoritative, nonauthoritative = nil)
+        @authoritative = authoritative
+        @nonauthoritative = nonauthoritative
+      end
+
+      #
+      # Returns the operation result for the authoritative origin.
+      #
+      # @return [OperationResult]
+      #
+      attr_reader :authoritative
+
+      #
+      # Returns the operation result for the non-authoritative origin.
+      #
+      # This result might be nil as the non-authoritative write does not execute in every stage, and will not execute
+      # if the authoritative write failed.
+      #
+      # @return [OperationResult, nil]
+      #
+      attr_reader :nonauthoritative
+    end
+
+
+    #
+    # The migration builder is used to configure and construct an instance of a
+    # {LaunchDarkly::Interfaces::Migrations::Migrator}. This migrator can be used to perform LaunchDarkly assisted
+    # technology migrations through the use of migration-based feature flags.
+    #
+    class MigratorBuilder
+      EXECUTION_SERIAL = :serial
+      EXECUTION_RANDOM = :random
+      EXECUTION_PARALLEL = :parallel
+
+      VALID_EXECUTION_ORDERS = [EXECUTION_SERIAL, EXECUTION_RANDOM, EXECUTION_PARALLEL]
+      private_constant :VALID_EXECUTION_ORDERS
+
+      #
+      # @param client [LaunchDarkly::LDClient]
+      #
+      def initialize(client)
+        @client = client
+
+        # Default settings as required by the spec
+        @read_execution_order = EXECUTION_PARALLEL
+        @measure_latency = true
+        @measure_errors = true
+
+        @read_config = nil # @type [LaunchDarkly::Impl::Migrations::MigrationConfig, nil]
+        @write_config = nil # @type [LaunchDarkly::Impl::Migrations::MigrationConfig, nil]
+      end
+
+      #
+      # The read execution order influences the parallelism and execution order for read operations involving multiple
+      # origins.
+      #
+      # @param order [Symbol]
+      #
+      def read_execution_order(order)
+        return unless VALID_EXECUTION_ORDERS.include? order
+
+        @read_execution_order = order
+      end
+
+      #
+      # Enable or disable latency tracking for migration operations. This latency information can be sent upstream to
+      # LaunchDarkly to enhance migration visibility.
+      #
+      # @param enabled [Boolean]
+      #
+      def track_latency(enabled)
+        @measure_latency = !!enabled
+      end
+
+      #
+      # Enable or disable error tracking for migration operations. This error information can be sent upstream to
+      # LaunchDarkly to enhance migration visibility.
+      #
+      # @param enabled [Boolean]
+      #
+      def track_errors(enabled)
+        @measure_errors = !!enabled
+      end
+
+      #
+      # Read can be used to configure the migration-read behavior of the resulting
+      # {LaunchDarkly::Interfaces::Migrations::Migrator} instance.
+      #
+      # Users are required to provide two different read methods -- one to read from the old migration origin, and one
+      # to read from the new origin. Additionally, customers can opt-in to consistency tracking by providing a
+      # comparison function.
+      #
+      # Depending on the migration stage, one or both of these read methods may be called.
+      #
+      # The read methods should accept a single nullable parameter. This parameter is a payload passed through the
+      # {LaunchDarkly::Interfaces::Migrations::Migrator#read} method. This method should return a {LaunchDarkly::Result}
+      # instance.
+      #
+      # The consistency method should accept 2 parameters of any type. These parameters are the results of executing the
+      # read operation against the old and new origins. If both operations were successful, the consistency method will
+      # be invoked. This method should return true if the two parameters are equal, or false otherwise.
+      #
+      # @param old_read [#call]
+      # @param new_read [#call]
+      # @param comparison [#call, nil]
+      #
+      def read(old_read, new_read, comparison = nil)
+        return unless old_read.respond_to?(:call) && old_read.arity == 1
+        return unless new_read.respond_to?(:call) && new_read.arity == 1
+        return unless comparison.nil? || (comparison.respond_to?(:call) && comparison.arity == 2)
+
+        @read_config = LaunchDarkly::Impl::Migrations::MigrationConfig.new(old_read, new_read, comparison)
+      end
+
+      #
+      # Write can be used to configure the migration-write behavior of the resulting
+      # {LaunchDarkly::Interfaces::Migrations::Migrator} instance.
+      #
+      # Users are required to provide two different write methods -- one to write to the old migration origin, and one
+      # to write to the new origin.
+      #
+      # Depending on the migration stage, one or both of these write methods may be called.
+      #
+      # The write methods should accept a single nullable parameter. This parameter is a payload passed through the
+      # {LaunchDarkly::Interfaces::Migrations::Migrator#write} method. This method should return a {LaunchDarkly::Result}
+      # instance.
+      #
+      # @param old_write [#call]
+      # @param new_write [#call]
+      #
+      def write(old_write, new_write)
+        return unless old_write.respond_to?(:call) && old_write.arity == 1
+        return unless new_write.respond_to?(:call) && new_write.arity == 1
+
+        @write_config = LaunchDarkly::Impl::Migrations::MigrationConfig.new(old_write, new_write, nil)
+      end
+
+      #
+      # Build constructs a {LaunchDarkly::Interfaces::Migrations::Migrator} instance to support migration-based reads
+      # and writes. A string describing any failure conditions will be returned if the build fails.
+      #
+      # @return [LaunchDarkly::Interfaces::Migrations::Migrator, string]
+      #
+      def build
+        return "client not provided" if @client.nil?
+        return "read configuration not provided" if @read_config.nil?
+        return "write configuration not provided" if @write_config.nil?
+
+        LaunchDarkly::Impl::Migrations::Migrator.new(@client, @read_execution_order, @read_config, @write_config, @measure_latency, @measure_errors)
+      end
+    end
+
+  end
+end

data/lib/ldclient-rb/non_blocking_thread_pool.rb

@@ -17,7 +17,7 @@ module LaunchDarkly
     # Attempts to submit a job, but only if a worker is available. Unlike the regular post method,
     # this returns a value: true if the job was submitted, false if all workers are busy.
     def post
-      if !@semaphore.try_acquire(1)
+      unless @semaphore.try_acquire(1)
         return
       end
       @pool.post do

data/lib/ldclient-rb/polling.rb

@@ -1,6 +1,7 @@
 require "ldclient-rb/impl/repeating_task"
 
 require "concurrent/atomics"
+require "json"
 require "thread"
 
 module LaunchDarkly
@@ -27,30 +28,75 @@ module LaunchDarkly
     end
 
     def stop
-      @task.stop
-      @config.logger.info { "[LDClient] Polling connection stopped" }
+      stop_with_error_info
     end
 
     def poll
       begin
         all_data = @requestor.request_all_data
         if all_data
-          @config.feature_store.init(all_data)
+          update_sink_or_data_store.init(all_data)
           if @initialized.make_true
             @config.logger.info { "[LDClient] Polling connection initialized" }
             @ready.set
           end
         end
+        @config.data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::VALID, nil)
+      rescue JSON::ParserError => e
+        @config.logger.error { "[LDClient] JSON parsing failed for polling response." }
+        error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+          LaunchDarkly::Interfaces::DataSource::ErrorInfo::INVALID_DATA,
+          0,
+          e.to_s,
+          Time.now
+        )
+        @config.data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED, error_info)
       rescue UnexpectedResponseError => e
+        error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+          LaunchDarkly::Interfaces::DataSource::ErrorInfo::ERROR_RESPONSE, e.status, nil, Time.now)
         message = Util.http_error_message(e.status, "polling request", "will retry")
-        @config.logger.error { "[LDClient] #{message}" };
-        if !Util.http_error_recoverable?(e.status)
+        @config.logger.error { "[LDClient] #{message}" }
+
+        if Util.http_error_recoverable?(e.status)
+          @config.data_source_update_sink&.update_status(
+            LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+            error_info
+          )
+        else
           @ready.set  # if client was waiting on us, make it stop waiting - has no effect if already set
-          stop
+          stop_with_error_info error_info
         end
       rescue StandardError => e
         Util.log_exception(@config.logger, "Exception while polling", e)
+        @config.data_source_update_sink&.update_status(
+          LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+          LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN, 0, e.to_s, Time.now)
+        )
       end
     end
+
+    #
+    # The original implementation of this class relied on the feature store
+    # directly, which we are trying to move away from. Customers who might have
+    # instantiated this directly for some reason wouldn't know they have to set
+    # the config's sink manually, so we have to fall back to the store if the
+    # sink isn't present.
+    #
+    # The next major release should be able to simplify this structure and
+    # remove the need for fall back to the data store because the update sink
+    # should always be present.
+    #
+    private def update_sink_or_data_store
+      @config.data_source_update_sink || @config.feature_store
+    end
+
+    #
+    # @param [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] error_info
+    #
+    private def stop_with_error_info(error_info = nil)
+      @task.stop
+      @config.logger.info { "[LDClient] Polling connection stopped" }
+      @config.data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::OFF, error_info)
+    end
   end
 end

data/lib/ldclient-rb/reference.rb

@@ -0,0 +1,274 @@
+module LaunchDarkly
+  #
+  # Reference is an attribute name or path expression identifying a value
+  # within a Context.
+  #
+  # This type is mainly intended to be used internally by LaunchDarkly SDK and
+  # service code, where efficiency is a major concern so it's desirable to do
+  # any parsing or preprocessing just once. Applications are unlikely to need
+  # to use the Reference type directly.
+  #
+  # It can be used to retrieve a value with LDContext.get_value_for_reference()
+  # or to identify an attribute or nested value that should be considered
+  # private.
+  #
+  # Parsing and validation are done at the time that the Reference is
+  # constructed. If a Reference instance was created from an invalid string, it
+  # is considered invalid and its {Reference#error} attribute will return a
+  # non-nil error.
+  #
+  # ## Syntax
+  #
+  # The string representation of an attribute reference in LaunchDarkly JSON
+  # data uses the following syntax:
+  #
+  # If the first character is not a slash, the string is interpreted literally
+  # as an attribute name. An attribute name can contain any characters, but
+  # must not be empty.
+  #
+  # If the first character is a slash, the string is interpreted as a
+  # slash-delimited path where the first path component is an attribute name,
+  # and each subsequent path component is the name of a property in a JSON
+  # object. Any instances of the characters "/" or "~" in a path component are
+  # escaped as "~1" or "~0" respectively. This syntax deliberately resembles
+  # JSON Pointer, but no JSON Pointer behaviors other than those mentioned here
+  # are supported.
+  #
+  # ## Examples
+  #
+  # Suppose there is a context whose JSON implementation looks like this:
+  #
+  #	{
+  #	  "kind": "user",
+  #	  "key": "value1",
+  #	  "address": {
+  #	    "street": {
+  #	      "line1": "value2",
+  #	      "line2": "value3"
+  #	    },
+  #	    "city": "value4"
+  #	  },
+  #	  "good/bad": "value5"
+  #	}
+  #
+  # The attribute references "key" and "/key" would both point to "value1".
+  #
+  # The attribute reference "/address/street/line1" would point to "value2".
+  #
+  # The attribute references "good/bad" and "/good~1bad" would both point to
+  # "value5".
+  #
+  class Reference
+    ERR_EMPTY = 'empty reference'
+    private_constant :ERR_EMPTY
+
+    ERR_INVALID_ESCAPE_SEQUENCE = 'invalid escape sequence'
+    private_constant :ERR_INVALID_ESCAPE_SEQUENCE
+
+    ERR_DOUBLE_TRAILING_SLASH = 'double or trailing slash'
+    private_constant :ERR_DOUBLE_TRAILING_SLASH
+
+    #
+    # Returns nil for a valid Reference, or a non-nil error value for an
+    # invalid Reference.
+    #
+    # A Reference is invalid if the input string is empty, or starts with a
+    # slash but is not a valid slash-delimited path, or starts with a slash and
+    # contains an invalid escape sequence.
+    #
+    # Otherwise, the Reference is valid, but that does not guarantee that such
+    # an attribute exists in any given Context. For instance,
+    # Reference.create("name") is a valid Reference, but a specific Context
+    # might or might not have a name.
+    #
+    # See comments on the Reference type for more details of the attribute
+    # reference syntax.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :error
+
+    #
+    # Returns the attribute reference as a string, in the same format provided
+    # to {#create}.
+    #
+    # If the Reference was created with {#create}, this value is identical to
+    # the original string. If it was created with {#create_literal}, the value
+    # may be different due to unescaping (for instance, an attribute whose name
+    # is "/a" would be represented as "~1a").
+    #
+    # @return [String, nil]
+    #
+    attr_reader :raw_path
+
+    def initialize(raw_path, components = [], error = nil)
+      @raw_path = raw_path
+      # @type [Array<Symbol>]
+      @components = components
+      @error = error
+    end
+    private_class_method :new
+
+    #
+    # Creates a Reference from a string. For the supported syntax and examples,
+    # see comments on the Reference type.
+    #
+    # This constructor always returns a Reference that preserves the original
+    # string, even if validation fails, so that accessing {#raw_path} (or
+    # serializing the Reference to JSON) will produce the original string. If
+    # validation fails, {#error} will return a non-nil error and any SDK method
+    # that takes this Reference as a parameter will consider it invalid.
+    #
+    # @param value [String, Symbol]
+    # @return [Reference]
+    #
+    def self.create(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        return new(value, [], ERR_EMPTY)
+      end
+
+      value = value.to_s if value.is_a?(Symbol)
+
+      return new(value, [], ERR_EMPTY) if value.empty? || value == "/"
+
+      unless value.start_with? "/"
+        return new(value, [value.to_sym])
+      end
+
+      if value.end_with? "/"
+        return new(value, [], ERR_DOUBLE_TRAILING_SLASH)
+      end
+
+      components = []
+      value[1..].split("/").each do |component|
+        if component.empty?
+          return new(value, [], ERR_DOUBLE_TRAILING_SLASH)
+        end
+
+        path, error = unescape_path(component)
+
+        if error
+          return new(value, [], error)
+        end
+
+        components << path.to_sym
+      end
+
+      new(value, components)
+    end
+
+    #
+    # create_literal is similar to {#create} except that it always
+    # interprets the string as a literal attribute name, never as a
+    # slash-delimited path expression. There is no escaping or unescaping, even
+    # if the name contains literal '/' or '~' characters. Since an attribute
+    # name can contain any characters, this method always returns a valid
+    # Reference unless the name is empty.
+    #
+    # For example: Reference.create_literal("name") is exactly equivalent to
+    # Reference.create("name"). Reference.create_literal("a/b") is exactly
+    # equivalent to Reference.create("a/b") (since the syntax used by {#create}
+    # treats the whole string as a literal as long as it does not start with a
+    # slash), or to Reference.create("/a~1b").
+    #
+    # @param value [String, Symbol]
+    # @return [Reference]
+    #
+    def self.create_literal(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        return new(value, [], ERR_EMPTY)
+      end
+
+      value = value.to_s if value.is_a?(Symbol)
+
+      return new(value, [], ERR_EMPTY) if value.empty?
+      return new(value, [value.to_sym]) if value[0] != '/'
+
+      escaped = "/" + value.gsub('~', '~0').gsub('/', '~1')
+      new(escaped, [value.to_sym])
+    end
+
+    #
+    # Returns the number of path components in the Reference.
+    #
+    # For a simple attribute reference such as "name" with no leading slash,
+    # this returns 1.
+    #
+    # For an attribute reference with a leading slash, it is the number of
+    # slash-delimited path components after the initial slash. For instance,
+    # NewRef("/a/b").Depth() returns 2.
+    #
+    # @return [Integer]
+    #
+    def depth
+      @components.size
+    end
+
+    #
+    # Retrieves a single path component from the attribute reference.
+    #
+    # For a simple attribute reference such as "name" with no leading slash, if
+    # index is zero, {#component} returns the attribute name as a symbol.
+    #
+    # For an attribute reference with a leading slash, if index is non-negative
+    # and less than {#depth}, Component returns the path component as a symbol.
+    #
+    # If index is out of range, it returns nil.
+    #
+    #	Reference.create("a").component(0)    # returns "a"
+    #	Reference.create("/a/b").component(1) # returns "b"
+    #
+    # @param index [Integer]
+    # @return [Symbol, nil]
+    #
+    def component(index)
+      return nil if index < 0 || index >= depth
+
+      @components[index]
+    end
+
+    #
+    # Performs unescaping of attribute reference path components:
+    #
+    # "~1" becomes "/"
+    # "~0" becomes "~"
+    # "~" followed by any character other than "0" or "1" is invalid
+    #
+    # This method returns an array of two values. The first element of the
+    # array is the path if unescaping was valid; otherwise, it will be nil. The
+    # second value is an error string, or nil if the unescaping was successful.
+    #
+    # @param path [String]
+    # @return [Array([String, nil], [String, nil])] Returns a fixed size array.
+    #
+    private_class_method def self.unescape_path(path)
+      # If there are no tildes then there's definitely nothing to do
+      return path, nil unless path.include? '~'
+
+      out = ""
+      i = 0
+      while i < path.size
+        if path[i] != "~"
+          out << path[i]
+          i += 1
+          next
+        end
+
+        return nil, ERR_INVALID_ESCAPE_SEQUENCE if i + 1 == path.size
+
+        case path[i + 1]
+        when '0'
+          out << "~"
+        when '1'
+          out << '/'
+        else
+          return nil, ERR_INVALID_ESCAPE_SEQUENCE
+        end
+
+        i += 2
+      end
+
+      [out, nil]
+    end
+  end
+end

data/lib/ldclient-rb/requestor.rb

@@ -31,9 +31,9 @@ module LaunchDarkly
 
     def request_all_data()
       all_data = JSON.parse(make_request("/sdk/latest-all"), symbolize_names: true)
-      Impl::Model.make_all_store_data(all_data)
+      Impl::Model.make_all_store_data(all_data, @config.logger)
     end
-    
+
     def stop
       begin
         @http_client.close
@@ -43,21 +43,19 @@ module LaunchDarkly
 
     private
 
-    def request_single_item(kind, path)
-      Impl::Model.deserialize(kind, make_request(path))
-    end
-
     def make_request(path)
-      uri = URI(@config.base_uri + path)
+      uri = URI(
+        Util.add_payload_filter_key(@config.base_uri + path, @config)
+      )
       headers = {}
       Impl::Util.default_http_headers(@sdk_key, @config).each { |k, v| headers[k] = v }
       headers["Connection"] = "keep-alive"
       cached = @cache.read(uri)
-      if !cached.nil?
+      unless cached.nil?
         headers["If-None-Match"] = cached.etag
       end
       response = @http_client.request("GET", uri, {
-        headers: headers
+        headers: headers,
       })
       status = response.status.code
       # must fully read body for persistent connections
@@ -72,7 +70,7 @@ module LaunchDarkly
         end
         body = fix_encoding(body, response.headers["content-type"])
         etag = response.headers["etag"]
-        @cache.write(uri, CacheEntry.new(etag, body)) if !etag.nil?
+        @cache.write(uri, CacheEntry.new(etag, body)) unless etag.nil?
       end
       body
     end
@@ -96,7 +94,7 @@ module LaunchDarkly
           break
         end
       end
-      return [parts[0], charset]
+      [parts[0], charset]
     end
   end
 end