launchdarkly-server-sdk 7.3.0 → 8.0.0

data/lib/ldclient-rb/interfaces.rb

@@ -788,5 +788,102 @@ module LaunchDarkly
         end
       end
     end
+
+    #
+    # Namespace for feature-flag based technology migration support.
+    #
+    module Migrations
+      #
+      # A migrator is the interface through which migration support is executed. A migrator is configured through the
+      # {LaunchDarkly::Migrations::MigratorBuilder} class.
+      #
+      module Migrator
+        #
+        # Uses the provided flag key and context to execute a migration-backed read operation.
+        #
+        # @param key [String]
+        # @param context [LaunchDarkly::LDContext]
+        # @param default_stage [Symbol]
+        # @param payload [Object, nil]
+        #
+        # @return [LaunchDarkly::Migrations::OperationResult]
+        #
+        def read(key, context, default_stage, payload = nil) end
+
+        #
+        # Uses the provided flag key and context to execute a migration-backed write operation.
+        #
+        # @param key [String]
+        # @param context [LaunchDarkly::LDContext]
+        # @param default_stage [Symbol]
+        # @param payload [Object, nil]
+        #
+        # @return [LaunchDarkly::Migrations::WriteResult]
+        #
+        def write(key, context, default_stage, payload = nil) end
+      end
+
+      #
+      # An OpTracker is responsible for managing the collection of measurements that which a user might wish to record
+      # throughout a migration-assisted operation.
+      #
+      # Example measurements include latency, errors, and consistency.
+      #
+      # This data can be provided to the {LaunchDarkly::LDClient.track_migration_op} method to relay this metric
+      # information upstream to LaunchDarkly services.
+      #
+      module OpTracker
+        #
+        # Sets the migration related operation associated with these tracking measurements.
+        #
+        # @param [Symbol] op The read or write operation symbol.
+        #
+        def operation(op) end
+
+        #
+        # Allows recording which origins were called during a migration.
+        #
+        # @param [Symbol] origin Designation for the old or new origin.
+        #
+        def invoked(origin) end
+
+        #
+        # Allows recording the results of a consistency check.
+        #
+        # This method accepts a callable which should take no parameters and return a single boolean to represent the
+        # consistency check results for a read operation.
+        #
+        # A callable is provided in case sampling rules do not require consistency checking to run. In this case, we can
+        # avoid the overhead of a function by not using the callable.
+        #
+        # @param [#call] is_consistent closure to return result of comparison check
+        #
+        def consistent(is_consistent) end
+
+        #
+        # Allows recording whether an error occurred during the operation.
+        #
+        # @param [Symbol] origin Designation for the old or new origin.
+        #
+        def error(origin) end
+
+        #
+        # Allows tracking the recorded latency for an individual operation.
+        #
+        # @param [Symbol] origin Designation for the old or new origin.
+        # @param [Float] duration Duration measurement in milliseconds (ms).
+        #
+        def latency(origin, duration) end
+
+        #
+        # Creates an instance of {LaunchDarkly::Impl::MigrationOpEventData}.
+        #
+        # @return [LaunchDarkly::Impl::MigrationOpEvent, String] A migration op event or a string describing the error.
+        # failure.
+        #
+        def build
+        end
+      end
+    end
   end
 end

data/lib/ldclient-rb/ldclient.rb

@@ -6,8 +6,10 @@ require "ldclient-rb/impl/diagnostic_events"
 require "ldclient-rb/impl/evaluator"
 require "ldclient-rb/impl/flag_tracker"
 require "ldclient-rb/impl/store_client_wrapper"
+require "ldclient-rb/impl/migrations/tracker"
 require "concurrent/atomics"
 require "digest/sha1"
+require "forwardable"
 require "logger"
 require "benchmark"
 require "json"
@@ -20,6 +22,10 @@ module LaunchDarkly
   #
   class LDClient
     include Impl
+    extend Forwardable
+
+    def_delegators :@config, :logger
+
     #
     # Creates a new client instance that connects to LaunchDarkly. A custom
     # configuration parameter can also supplied to specify advanced options,
@@ -148,7 +154,7 @@ module LaunchDarkly
     # @return [String, nil] a hash string or nil if the provided context was invalid
     #
     def secure_mode_hash(context)
-      context = Impl::Context::make_context(context)
+      context = Impl::Context.make_context(context)
       unless context.valid?
         @config.logger.warn("secure_mode_hash called with invalid context: #{context.error}")
         return nil
@@ -188,10 +194,11 @@ module LaunchDarkly
     # @param default the default value of the flag; this is used if there is an error
     #   condition making it impossible to find or evaluate the flag
     #
-    # @return the variation for the provided context, or the default value if there's an an error
+    # @return the variation for the provided context, or the default value if there's an error
     #
     def variation(key, context, default)
-      evaluate_internal(key, context, default, false).value
+      detail, _, _, = variation_with_flag(key, context, default)
+      detail.value
     end
 
     #
@@ -218,7 +225,43 @@ module LaunchDarkly
     # @return [EvaluationDetail] an object describing the result
     #
     def variation_detail(key, context, default)
-      evaluate_internal(key, context, default, true)
+      detail, _, _ = evaluate_internal(key, context, default, true)
+      detail
+    end
+
+    #
+    # This method returns the migration stage of the migration feature flag for the given evaluation context.
+    #
+    # This method returns the default stage if there is an error or the flag does not exist. If the default stage is not
+    # a valid stage, then a default stage of 'off' will be used instead.
+    #
+    # @param key [String]
+    # @param context [LDContext]
+    # @param default_stage [Symbol]
+    #
+    # @return [Array<Symbol, Interfaces::Migrations::OpTracker>]
+    #
+    def migration_variation(key, context, default_stage)
+      unless Migrations::VALID_STAGES.include? default_stage
+        @config.logger.error { "[LDClient] default_stage #{default_stage} is not a valid stage; continuing with 'off' as default" }
+        default_stage = Migrations::STAGE_OFF
+      end
+
+      context = Impl::Context::make_context(context)
+      detail, flag, _ = variation_with_flag(key, context, default_stage.to_s)
+
+      stage = detail.value
+      stage = stage.to_sym if stage.respond_to? :to_sym
+
+      if Migrations::VALID_STAGES.include?(stage)
+        tracker = Impl::Migrations::OpTracker.new(@config.logger, key, flag, context, detail, default_stage)
+        return stage, tracker
+      end
+
+      detail = LaunchDarkly::Impl::Evaluator.error_result(LaunchDarkly::EvaluationReason::ERROR_WRONG_TYPE, default_stage.to_s)
+      tracker = Impl::Migrations::OpTracker.new(@config.logger, key, flag, context, detail, default_stage)
+
+      [default_stage, tracker]
     end
 
     #
@@ -281,6 +324,32 @@ module LaunchDarkly
       @event_processor.record_custom_event(context, event_name, data, metric_value)
     end
 
+    #
+    # Tracks the results of a migrations operation. This event includes measurements which can be used to enhance the
+    # observability of a migration within the LaunchDarkly UI.
+    #
+    # This event should be generated through {Interfaces::Migrations::OpTracker}. If you are using the
+    # {Interfaces::Migrations::Migrator} to handle migrations, this event will be created and emitted
+    # automatically.
+    #
+    # @param tracker [LaunchDarkly::Interfaces::Migrations::OpTracker]
+    #
+    def track_migration_op(tracker)
+      unless tracker.is_a? LaunchDarkly::Interfaces::Migrations::OpTracker
+        @config.logger.error { "invalid op tracker received in track_migration_op" }
+        return
+      end
+
+      event = tracker.build
+      if event.is_a? String
+        @config.logger.error { "[LDClient] Error occurred generating migration op event; #{event}" }
+        return
+      end
+
+
+      @event_processor.record_migration_op_event(event)
+    end
+
     #
     # Returns a {FeatureFlagsState} object that encapsulates the state of all feature flags for a given context,
     # including the flag values and also metadata that can be used on the front end. This method does not
@@ -430,24 +499,41 @@ module LaunchDarkly
       end
     end
 
+    #
+    # @param key [String]
     # @param context [Hash, LDContext]
-    # @return [EvaluationDetail]
+    # @param default [Object]
+    #
+    # @return [Array<EvaluationDetail, [LaunchDarkly::Impl::Model::FeatureFlag, nil], [String, nil]>]
+    #
+    def variation_with_flag(key, context, default)
+      evaluate_internal(key, context, default, false)
+    end
+
+    #
+    # @param key [String]
+    # @param context [Hash, LDContext]
+    # @param default [Object]
+    # @param with_reasons [Boolean]
+    #
+    # @return [Array<EvaluationDetail, [LaunchDarkly::Impl::Model::FeatureFlag, nil], [String, nil]>]
+    #
     def evaluate_internal(key, context, default, with_reasons)
       if @config.offline?
-        return Evaluator.error_result(EvaluationReason::ERROR_CLIENT_NOT_READY, default)
+        return Evaluator.error_result(EvaluationReason::ERROR_CLIENT_NOT_READY, default), nil, nil
       end
 
       if context.nil?
         @config.logger.error { "[LDClient] Must specify context" }
         detail = Evaluator.error_result(EvaluationReason::ERROR_USER_NOT_SPECIFIED, default)
-        return detail
+        return detail, nil, "no context provided"
       end
 
       context = Impl::Context::make_context(context)
       unless context.valid?
         @config.logger.error { "[LDClient] Context was invalid for evaluation of flag '#{key}' (#{context.error}); returning default value" }
         detail = Evaluator.error_result(EvaluationReason::ERROR_USER_NOT_SPECIFIED, default)
-        return detail
+        return detail, nil, context.error
       end
 
       unless initialized?
@@ -457,7 +543,7 @@ module LaunchDarkly
           @config.logger.error { "[LDClient] Client has not finished initializing; feature store unavailable, returning default value" }
           detail = Evaluator.error_result(EvaluationReason::ERROR_CLIENT_NOT_READY, default)
           record_unknown_flag_eval(key, context, default, detail.reason, with_reasons)
-          return detail
+          return detail, nil, "client not initialized"
         end
       end
 
@@ -471,7 +557,7 @@ module LaunchDarkly
         @config.logger.info { "[LDClient] Unknown feature flag \"#{key}\". Returning default value" }
         detail = Evaluator.error_result(EvaluationReason::ERROR_FLAG_NOT_FOUND, default)
         record_unknown_flag_eval(key, context, default, detail.reason, with_reasons)
-        return detail
+        return detail, nil, "feature flag not found"
       end
 
       begin
@@ -486,12 +572,12 @@ module LaunchDarkly
           detail = EvaluationDetail.new(default, nil, detail.reason)
         end
         record_flag_eval(feature, context, detail, default, with_reasons)
-        detail
+        [detail, feature, nil]
       rescue => exn
         Util.log_exception(@config.logger, "Error evaluating feature flag \"#{key}\"", exn)
         detail = Evaluator.error_result(EvaluationReason::ERROR_EXCEPTION, default)
         record_flag_eval_error(feature, context, default, detail.reason, with_reasons)
-        detail
+        [detail, feature, exn.to_s]
       end
     end
 
@@ -507,7 +593,9 @@ module LaunchDarkly
         default,
         add_experiment_data || flag[:trackEvents] || false,
         flag[:debugEventsUntilDate],
-        nil
+        nil,
+        flag[:samplingRatio],
+        !!flag[:excludeFromSummaries]
       )
     end
 
@@ -523,13 +611,15 @@ module LaunchDarkly
         nil,
         add_experiment_data || prereq_flag[:trackEvents] || false,
         prereq_flag[:debugEventsUntilDate],
-        prereq_of_flag[:key]
+        prereq_of_flag[:key],
+        prereq_flag[:samplingRatio],
+        !!prereq_flag[:excludeFromSummaries]
       )
     end
 
     private def record_flag_eval_error(flag, context, default, reason, with_reasons)
       @event_processor.record_eval_event(context, flag[:key], flag[:version], nil, default, with_reasons ? reason : nil, default,
-        flag[:trackEvents], flag[:debugEventsUntilDate], nil)
+        flag[:trackEvents], flag[:debugEventsUntilDate], nil, flag[:samplingRatio], !!flag[:excludeFromSummaries])
     end
 
     #
@@ -541,7 +631,7 @@ module LaunchDarkly
     #
     private def record_unknown_flag_eval(flag_key, context, default, reason, with_reasons)
       @event_processor.record_eval_event(context, flag_key, nil, nil, default, with_reasons ? reason : nil, default,
-        false, nil, nil)
+        false, nil, nil, 1, false)
     end
 
     private def experiment?(flag, reason)

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/util.rb

@@ -2,6 +2,69 @@ 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
     #

data/lib/ldclient-rb/version.rb

@@ -1,3 +1,3 @@
 module LaunchDarkly
-  VERSION = "7.3.0"
+  VERSION = "8.0.0"
 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"