launchdarkly-server-sdk 7.0.2 → 8.4.2

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/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}" }
-        unless Util.http_error_recoverable?(e.status)
+
+        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

@@ -109,6 +109,8 @@ module LaunchDarkly
     end
     private_class_method :new
 
+    protected attr_reader :components
+
     #
     # Creates a Reference from a string. For the supported syntax and examples,
     # see comments on the Reference type.
@@ -227,6 +229,15 @@ module LaunchDarkly
       @components[index]
     end
 
+    def ==(other)
+      self.error == other.error && self.components == other.components
+    end
+    alias eql? ==
+
+    def hash
+      ([error] + components).hash
+    end
+
     #
     # Performs unescaping of attribute reference path components:
     #

data/lib/ldclient-rb/requestor.rb

@@ -26,6 +26,8 @@ module LaunchDarkly
       @sdk_key = sdk_key
       @config = config
       @http_client = LaunchDarkly::Util.new_http_client(config.base_uri, config)
+        .use(:auto_inflate)
+        .headers("Accept-Encoding" => "gzip")
       @cache = @config.cache_store
     end
 
@@ -43,12 +45,10 @@ module LaunchDarkly
 
     private
 
-    def request_single_item(kind, path)
-      Impl::Model.deserialize(kind, make_request(path), @config.logger)
-    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"

data/lib/ldclient-rb/stream.rb

@@ -25,6 +25,7 @@ module LaunchDarkly
     def initialize(sdk_key, config, diagnostic_accumulator = nil)
       @sdk_key = sdk_key
       @config = config
+      @data_source_update_sink = config.data_source_update_sink
       @feature_store = config.feature_store
       @initialized = Concurrent::AtomicBoolean.new(false)
       @started = Concurrent::AtomicBoolean.new(false)
@@ -51,19 +52,40 @@ module LaunchDarkly
         reconnect_time: @config.initial_reconnect_delay,
       }
       log_connection_started
-      @es = SSE::Client.new(@config.stream_uri + "/all", **opts) do |conn|
+
+      uri = Util.add_payload_filter_key(@config.stream_uri + "/all", @config)
+      @es = SSE::Client.new(uri, **opts) do |conn|
         conn.on_event { |event| process_message(event) }
         conn.on_error { |err|
           log_connection_result(false)
           case err
           when SSE::Errors::HTTPStatusError
             status = err.status
+            error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+              LaunchDarkly::Interfaces::DataSource::ErrorInfo::ERROR_RESPONSE, status, nil, Time.now)
             message = Util.http_error_message(status, "streaming connection", "will retry")
             @config.logger.error { "[LDClient] #{message}" }
-            unless Util.http_error_recoverable?(status)
+
+            if Util.http_error_recoverable?(status)
+              @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
+          when SSE::Errors::HTTPContentTypeError, SSE::Errors::HTTPProxyError, SSE::Errors::ReadTimeoutError
+            @data_source_update_sink&.update_status(
+              LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+              LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(LaunchDarkly::Interfaces::DataSource::ErrorInfo::NETWORK_ERROR, 0, err.to_s, Time.now)
+            )
+
+          else
+            @data_source_update_sink&.update_status(
+              LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+              LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN, 0, err.to_s, Time.now)
+            )
           end
         }
       end
@@ -72,46 +94,86 @@ module LaunchDarkly
     end
 
     def stop
+      stop_with_error_info
+    end
+
+    private
+
+    #
+    # @param [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] error_info
+    #
+    def stop_with_error_info(error_info = nil)
       if @stopped.make_true
         @es.close
+        @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::OFF, error_info)
         @config.logger.info { "[LDClient] Stream connection stopped" }
       end
     end
 
-    private
+    #
+    # 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.
+    #
+    def update_sink_or_data_store
+      @data_source_update_sink || @feature_store
+    end
 
     def process_message(message)
       log_connection_result(true)
       method = message.type
       @config.logger.debug { "[LDClient] Stream received #{method} message: #{message.data}" }
-      if method == PUT
-        message = JSON.parse(message.data, symbolize_names: true)
-        all_data = Impl::Model.make_all_store_data(message[:data], @config.logger)
-        @feature_store.init(all_data)
-        @initialized.make_true
-        @config.logger.info { "[LDClient] Stream initialized" }
-        @ready.set
-      elsif method == PATCH
-        data = JSON.parse(message.data, symbolize_names: true)
-        for kind in [FEATURES, SEGMENTS]
-          key = key_for_path(kind, data[:path])
-          if key
-            item = Impl::Model.deserialize(kind, data[:data], @config.logger)
-            @feature_store.upsert(kind, item)
-            break
+
+      begin
+        if method == PUT
+          message = JSON.parse(message.data, symbolize_names: true)
+          all_data = Impl::Model.make_all_store_data(message[:data], @config.logger)
+          update_sink_or_data_store.init(all_data)
+          @initialized.make_true
+          @config.logger.info { "[LDClient] Stream initialized" }
+          @ready.set
+        elsif method == PATCH
+          data = JSON.parse(message.data, symbolize_names: true)
+          for kind in [FEATURES, SEGMENTS]
+            key = key_for_path(kind, data[:path])
+            if key
+              item = Impl::Model.deserialize(kind, data[:data], @config.logger)
+              update_sink_or_data_store.upsert(kind, item)
+              break
+            end
           end
-        end
-      elsif method == DELETE
-        data = JSON.parse(message.data, symbolize_names: true)
-        for kind in [FEATURES, SEGMENTS]
-          key = key_for_path(kind, data[:path])
-          if key
-            @feature_store.delete(kind, key, data[:version])
-            break
+        elsif method == DELETE
+          data = JSON.parse(message.data, symbolize_names: true)
+          for kind in [FEATURES, SEGMENTS]
+            key = key_for_path(kind, data[:path])
+            if key
+              update_sink_or_data_store.delete(kind, key, data[:version])
+              break
+            end
           end
+        else
+          @config.logger.warn { "[LDClient] Unknown message received: #{method}" }
         end
-      else
-        @config.logger.warn { "[LDClient] Unknown message received: #{method}" }
+
+        @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::VALID, nil)
+      rescue JSON::ParserError => e
+        @config.logger.error { "[LDClient] JSON parsing failed for method #{method}. Ignoring event." }
+        error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+          LaunchDarkly::Interfaces::DataSource::ErrorInfo::INVALID_DATA,
+          0,
+          e.to_s,
+          Time.now
+        )
+        @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED, error_info)
+
+        # Re-raise the exception so the SSE implementation can catch it and restart the stream.
+        raise
       end
     end
 

data/lib/ldclient-rb/util.rb

@@ -2,8 +2,97 @@ require "uri"
 require "http"
 
 module LaunchDarkly
+  #
+  # A Result is used to reflect the outcome of any operation.
+  #
+  # Results can either be considered a success or a failure.
+  #
+  # In the event of success, the Result will contain an option, nullable value to hold any success value back to the
+  # calling function.
+  #
+  # If the operation fails, the Result will contain an error describing the value.
+  #
+  class Result
+    #
+    # Create a successful result with the provided value.
+    #
+    # @param value [Object, nil]
+    # @return [Result]
+    #
+    def self.success(value)
+      Result.new(value)
+    end
+
+    #
+    # Create a failed result with the provided error description.
+    #
+    # @param error [String]
+    # @param exception [Exception, nil]
+    # @return [Result]
+    #
+    def self.fail(error, exception = nil)
+      Result.new(nil, error, exception)
+    end
+
+    #
+    # Was this result successful or did it encounter an error?
+    #
+    # @return [Boolean]
+    #
+    def success?
+      @error.nil?
+    end
+
+    #
+    # @return [Object, nil] The value returned from the operation if it was successful; nil otherwise.
+    #
+    attr_reader :value
+
+    #
+    # @return [String, nil] An error description of the failure; nil otherwise
+    #
+    attr_reader :error
+
+    #
+    # @return [Exception, nil] An optional exception which caused the failure
+    #
+    attr_reader :exception
+
+    private def initialize(value, error = nil, exception = nil)
+      @value = value
+      @error = error
+      @exception = exception
+    end
+  end
+
   # @private
   module Util
+    #
+    # Append the payload filter key query parameter to the provided URI.
+    #
+    # @param uri [String]
+    # @param config [Config]
+    # @return [String]
+    #
+    def self.add_payload_filter_key(uri, config)
+      return uri if config.payload_filter_key.nil?
+
+      unless config.payload_filter_key.is_a?(String) && !config.payload_filter_key.empty?
+        config.logger.warn { "[LDClient] Filter key must be a non-empty string. No filtering will be applied." }
+        return uri
+      end
+
+      begin
+        parsed = URI.parse(uri)
+        new_query_params = URI.decode_www_form(String(parsed.query)) << ["filter", config.payload_filter_key]
+        parsed.query = URI.encode_www_form(new_query_params)
+        parsed.to_s
+      rescue URI::InvalidURIError
+        config.logger.warn { "[LDClient] URI could not be parsed. No filtering will be applied." }
+        uri
+      end
+    end
+
     def self.new_http_client(uri_s, config)
       http_client_options = {}
       if config.socket_factory

data/lib/ldclient-rb/version.rb

@@ -1,3 +1,3 @@
 module LaunchDarkly
-  VERSION = "7.0.2"
+  VERSION = "8.4.2" # x-release-please-version
 end

data/lib/ldclient-rb.rb

@@ -9,6 +9,7 @@ require "ldclient-rb/version"
 require "ldclient-rb/interfaces"
 require "ldclient-rb/util"
 require "ldclient-rb/flags_state"
+require "ldclient-rb/migrations"
 require "ldclient-rb/ldclient"
 require "ldclient-rb/cache_store"
 require "ldclient-rb/expiring_cache"