launchdarkly-server-sdk 7.3.2 → 8.0.0

data/lib/ldclient-rb/impl/migrations/migrator.rb

@@ -0,0 +1,287 @@
+require 'thread'
+
+module LaunchDarkly
+  module Impl
+    module Migrations
+
+      #
+      # A migration config stores references to callable methods which execute customer defined read or write
+      # operations on old or new origins of information. For read operations, an optional comparison function also be
+      # defined.
+      #
+      class MigrationConfig
+        #
+        # @param old [#call] Refer to {#old}
+        # @param new [#call] Refer to {#new}
+        # @param comparison [#call, nil] Refer to {#comparison}
+        #
+        def initialize(old, new, comparison)
+          @old = old
+          @new = new
+          @comparison = comparison
+        end
+
+        #
+        # Callable which receives a nullable payload parameter and returns an {LaunchDarkly::Result}.
+        #
+        # This function call should affect the old migration origin when called.
+        #
+        # @return [#call]
+        #
+        attr_reader :old
+
+        #
+        # Callable which receives a nullable payload parameter and returns an {LaunchDarkly::Result}.
+        #
+        # This function call should affect the new migration origin when called.
+        #
+        # @return [#call]
+        #
+        attr_reader :new
+
+        #
+        # Optional callable which receives two objects of any kind and returns a boolean representing equality.
+        #
+        # The result of this comparison can be sent upstream to LaunchDarkly to enhance migration observability.
+        #
+        # @return [#call, nil]
+        #
+        attr_reader :comparison
+      end
+
+      #
+      # An implementation of the [LaunchDarkly::Interfaces::Migrations::Migrator] interface, capable of supporting
+      # feature-flag backed technology migrations.
+      #
+      class Migrator
+        include LaunchDarkly::Interfaces::Migrations::Migrator
+
+        #
+        # @param client [LaunchDarkly::LDClient]
+        # @param read_execution_order [Symbol]
+        # @param read_config [MigrationConfig]
+        # @param write_config [MigrationConfig]
+        # @param measure_latency [Boolean]
+        # @param measure_errors [Boolean]
+        #
+        def initialize(client, read_execution_order, read_config, write_config, measure_latency, measure_errors)
+          @client = client
+          @read_execution_order = read_execution_order
+          @read_config = read_config
+          @write_config = write_config
+          @measure_latency = measure_latency
+          @measure_errors = measure_errors
+          @sampler = LaunchDarkly::Impl::Sampler.new(Random.new)
+        end
+
+        #
+        # Perform the configured read operations against the appropriate old and/or new origins.
+        #
+        # @param key [String] The migration-based flag key to use for determining migration stages
+        # @param context [LaunchDarkly::LDContext] The context to use for evaluating the migration flag
+        # @param default_stage [Symbol] The stage to fallback to if one could not be determined for the requested flag
+        # @param payload [String] An optional payload to pass through to the configured read operations.
+        #
+        # @return [LaunchDarkly::Migrations::OperationResult]
+        #
+        def read(key, context, default_stage, payload = nil)
+          stage, tracker = @client.migration_variation(key, context, default_stage)
+          tracker.operation(LaunchDarkly::Migrations::OP_READ)
+
+          old = Executor.new(@client.logger, LaunchDarkly::Migrations::ORIGIN_OLD, @read_config.old, tracker, @measure_latency, @measure_errors, payload)
+          new = Executor.new(@client.logger, LaunchDarkly::Migrations::ORIGIN_NEW, @read_config.new, tracker, @measure_latency, @measure_errors, payload)
+
+          case stage
+          when LaunchDarkly::Migrations::STAGE_OFF
+            result = old.run
+          when LaunchDarkly::Migrations::STAGE_DUALWRITE
+            result = old.run
+          when LaunchDarkly::Migrations::STAGE_SHADOW
+            result = read_both(old, new, @read_config.comparison, @read_execution_order, tracker)
+          when LaunchDarkly::Migrations::STAGE_LIVE
+            result = read_both(new, old, @read_config.comparison, @read_execution_order, tracker)
+          when LaunchDarkly::Migrations::STAGE_RAMPDOWN
+            result = new.run
+          when LaunchDarkly::Migrations::STAGE_COMPLETE
+            result = new.run
+          else
+            result = LaunchDarkly::Migrations::OperationResult.new(
+              LaunchDarkly::Migrations::ORIGIN_OLD,
+              LaunchDarkly::Result.fail("invalid stage #{stage}; cannot execute read")
+            )
+          end
+
+          @client.track_migration_op(tracker)
+
+          result
+        end
+
+        #
+        # Perform the configured write operations against the appropriate old and/or new origins.
+        #
+        # @param key [String] The migration-based flag key to use for determining migration stages
+        # @param context [LaunchDarkly::LDContext] The context to use for evaluating the migration flag
+        # @param default_stage [Symbol] The stage to fallback to if one could not be determined for the requested flag
+        # @param payload [String] An optional payload to pass through to the configured write operations.
+        #
+        # @return [LaunchDarkly::Migrations::WriteResult]
+        #
+        def write(key, context, default_stage, payload = nil)
+          stage, tracker = @client.migration_variation(key, context, default_stage)
+          tracker.operation(LaunchDarkly::Migrations::OP_WRITE)
+
+          old = Executor.new(@client.logger, LaunchDarkly::Migrations::ORIGIN_OLD, @write_config.old, tracker, @measure_latency, @measure_errors, payload)
+          new = Executor.new(@client.logger, LaunchDarkly::Migrations::ORIGIN_NEW, @write_config.new, tracker, @measure_latency, @measure_errors, payload)
+
+          case stage
+          when LaunchDarkly::Migrations::STAGE_OFF
+            result = old.run()
+            write_result = LaunchDarkly::Migrations::WriteResult.new(result)
+          when LaunchDarkly::Migrations::STAGE_DUALWRITE
+            authoritative_result, nonauthoritative_result = write_both(old, new, tracker)
+            write_result = LaunchDarkly::Migrations::WriteResult.new(authoritative_result, nonauthoritative_result)
+          when LaunchDarkly::Migrations::STAGE_SHADOW
+            authoritative_result, nonauthoritative_result = write_both(old, new, tracker)
+            write_result = LaunchDarkly::Migrations::WriteResult.new(authoritative_result, nonauthoritative_result)
+          when LaunchDarkly::Migrations::STAGE_LIVE
+            authoritative_result, nonauthoritative_result = write_both(new, old, tracker)
+            write_result = LaunchDarkly::Migrations::WriteResult.new(authoritative_result, nonauthoritative_result)
+          when LaunchDarkly::Migrations::STAGE_RAMPDOWN
+            authoritative_result, nonauthoritative_result = write_both(new, old, tracker)
+            write_result = LaunchDarkly::Migrations::WriteResult.new(authoritative_result, nonauthoritative_result)
+          when LaunchDarkly::Migrations::STAGE_COMPLETE
+            result = new.run()
+            write_result = LaunchDarkly::Migrations::WriteResult.new(result)
+          else
+            result = LaunchDarkly::Migrations::OperationResult.fail(
+              LaunchDarkly::Migrations::ORIGIN_OLD,
+              LaunchDarkly::Result.fail("invalid stage #{stage}; cannot execute write")
+            )
+            write_result = LaunchDarkly::Migrations::WriteResult.new(result)
+          end
+
+          @client.track_migration_op(tracker)
+
+          write_result
+        end
+
+        #
+        # Execute both read methods in accordance with the requested execution order.
+        #
+        # This method always returns the {LaunchDarkly::Migrations::OperationResult} from running the authoritative read operation. The
+        # non-authoritative executor may fail but it will not affect the return value.
+        #
+        # @param authoritative [Executor]
+        # @param nonauthoritative [Executor]
+        # @param comparison [#call]
+        # @param execution_order [Symbol]
+        # @param tracker [LaunchDarkly::Interfaces::Migrations::OpTracker]
+        #
+        # @return [LaunchDarkly::Migrations::OperationResult]
+        #
+        private def read_both(authoritative, nonauthoritative, comparison, execution_order, tracker)
+          authoritative_result = nil
+          nonauthoritative_result = nil
+
+          case execution_order
+          when LaunchDarkly::Migrations::MigratorBuilder::EXECUTION_PARALLEL
+            auth_handler = Thread.new { authoritative_result = authoritative.run }
+            nonauth_handler = Thread.new { nonauthoritative_result = nonauthoritative.run }
+
+            auth_handler.join()
+            nonauth_handler.join()
+          when LaunchDarkly::Migrations::MigratorBuilder::EXECUTION_RANDOM && @sampler.sample(2)
+            nonauthoritative_result = nonauthoritative.run
+            authoritative_result = authoritative.run
+          else
+            authoritative_result = authoritative.run
+            nonauthoritative_result = nonauthoritative.run
+          end
+
+          return authoritative_result if comparison.nil?
+
+          if authoritative_result.success? && nonauthoritative_result.success?
+            tracker.consistent(->{ comparison.call(authoritative_result.value, nonauthoritative_result.value) })
+          end
+
+          authoritative_result
+        end
+
+        #
+        # Execute both operations sequentially.
+        #
+        # If the authoritative executor fails, do not run the non-authoritative one. As a result, this method will
+        # always return an authoritative {LaunchDarkly::Migrations::OperationResult} as the first value, and optionally the non-authoritative
+        # {LaunchDarkly::Migrations::OperationResult} as the second value.
+        #
+        # @param authoritative [Executor]
+        # @param nonauthoritative [Executor]
+        # @param tracker [LaunchDarkly::Interfaces::Migrations::OpTracker]
+        #
+        # @return [Array<LaunchDarkly::Migrations::OperationResult, [LaunchDarkly::Migrations::OperationResult, nil]>]
+        #
+        private def write_both(authoritative, nonauthoritative, tracker)
+          authoritative_result = authoritative.run()
+          tracker.invoked(authoritative.origin)
+
+          return authoritative_result, nil unless authoritative_result.success?
+
+          nonauthoritative_result = nonauthoritative.run()
+          tracker.invoked(nonauthoritative.origin)
+
+          [authoritative_result, nonauthoritative_result]
+        end
+      end
+
+      #
+      # Utility class for executing migration operations while also tracking our built-in migration measurements.
+      #
+      class Executor
+        #
+        # @return [Symbol]
+        #
+        attr_reader :origin
+
+        #
+        # @param origin [Symbol]
+        # @param fn [#call]
+        # @param tracker [LaunchDarkly::Interfaces::Migrations::OpTracker]
+        # @param measure_latency [Boolean]
+        # @param measure_errors [Boolean]
+        # @param payload [Object, nil]
+        #
+        def initialize(logger, origin, fn, tracker, measure_latency, measure_errors, payload)
+          @logger = logger
+          @origin = origin
+          @fn = fn
+          @tracker = tracker
+          @measure_latency = measure_latency
+          @measure_errors = measure_errors
+          @payload = payload
+        end
+
+        #
+        # Execute the configured operation and track any available measurements.
+        #
+        # @return [LaunchDarkly::Migrations::OperationResult]
+        #
+        def run()
+          start = Time.now
+
+          begin
+            result = @fn.call(@payload)
+          rescue => e
+            LaunchDarkly::Util.log_exception(@logger, "Unexpected error running method for '#{origin}' origin", e)
+            result = LaunchDarkly::Result.fail("'#{origin}' operation raised an exception", e)
+          end
+
+          @tracker.latency(@origin, (Time.now - start) * 1_000) if @measure_latency
+          @tracker.error(@origin) if @measure_errors && !result.success?
+          @tracker.invoked(@origin)
+
+          LaunchDarkly::Migrations::OperationResult.new(@origin, result)
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-rb/impl/migrations/tracker.rb

@@ -0,0 +1,136 @@
+require "set"
+require "ldclient-rb/impl/sampler"
+require "logger"
+
+module LaunchDarkly
+  module Impl
+    module Migrations
+      class OpTracker
+        include LaunchDarkly::Interfaces::Migrations::OpTracker
+
+        #
+        # @param logger [Logger] logger
+        # @param key [string] key
+        # @param flag [LaunchDarkly::Impl::Model::FeatureFlag] flag
+        # @param context [LaunchDarkly::LDContext] context
+        # @param detail [LaunchDarkly::EvaluationDetail] detail
+        # @param default_stage [Symbol] default_stage
+        #
+        def initialize(logger, key, flag, context, detail, default_stage)
+          @logger = logger
+          @key = key
+          @flag = flag
+          @context = context
+          @detail = detail
+          @default_stage = default_stage
+          @sampler = LaunchDarkly::Impl::Sampler.new(Random.new)
+
+          @mutex = Mutex.new
+
+          # @type [Symbol, nil]
+          @operation = nil
+
+          # @type [Set<Symbol>]
+          @invoked = Set.new
+          # @type [Boolean, nil]
+          @consistent = nil
+
+          # @type [Int]
+          @consistent_ratio = @flag&.migration_settings&.check_ratio
+          @consistent_ratio = 1 if @consistent_ratio.nil?
+
+          # @type [Set<Symbol>]
+          @errors = Set.new
+          # @type [Hash<Symbol, Float>]
+          @latencies = Hash.new
+        end
+
+        def operation(operation)
+          return unless LaunchDarkly::Migrations::VALID_OPERATIONS.include? operation
+
+          @mutex.synchronize do
+            @operation = operation
+          end
+        end
+
+        def invoked(origin)
+          return unless LaunchDarkly::Migrations::VALID_ORIGINS.include? origin
+
+          @mutex.synchronize do
+            @invoked.add(origin)
+          end
+        end
+
+        def consistent(is_consistent)
+          @mutex.synchronize do
+            if @sampler.sample(@consistent_ratio)
+              begin
+                @consistent = is_consistent.call
+              rescue => e
+                LaunchDarkly::Util.log_exception(@logger, "Exception raised during consistency check; failed to record measurement", e)
+              end
+            end
+          end
+        end
+
+        def error(origin)
+          return unless LaunchDarkly::Migrations::VALID_ORIGINS.include? origin
+
+          @mutex.synchronize do
+            @errors.add(origin)
+          end
+        end
+
+        def latency(origin, duration)
+          return unless LaunchDarkly::Migrations::VALID_ORIGINS.include? origin
+          return unless duration.is_a? Numeric
+          return if duration < 0
+
+          @mutex.synchronize do
+            @latencies[origin] = duration
+          end
+        end
+
+        def build
+          @mutex.synchronize do
+            return "operation cannot contain an empty key" if @key.empty?
+            return "operation not provided" if @operation.nil?
+            return "no origins were invoked" if @invoked.empty?
+            return "provided context was invalid" unless @context.valid?
+
+            result = check_invoked_consistency
+            return result unless result == true
+
+            LaunchDarkly::Impl::MigrationOpEvent.new(
+              LaunchDarkly::Impl::Util.current_time_millis,
+              @context,
+              @key,
+              @flag,
+              @operation,
+              @default_stage,
+              @detail,
+              @invoked,
+              @consistent,
+              @consistent_ratio,
+              @errors,
+              @latencies
+            )
+          end
+        end
+
+        private def check_invoked_consistency
+          LaunchDarkly::Migrations::VALID_ORIGINS.each do |origin|
+            next if @invoked.include? origin
+
+            return "provided latency for origin '#{origin}' without recording invocation" if @latencies.include? origin
+            return "provided error for origin '#{origin}' without recording invocation" if @errors.include? origin
+          end
+
+          return "provided consistency without recording both invocations" if !@consistent.nil? && @invoked.size != 2
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-rb/impl/model/feature_flag.rb

@@ -26,6 +26,10 @@ module LaunchDarkly
           @version = data[:version]
           @deleted = !!data[:deleted]
           return if @deleted
+          migration_settings = data[:migration] || {}
+          @migration_settings = MigrationSettings.new(migration_settings[:checkRatio])
+          @sampling_ratio = data[:samplingRatio]
+          @exclude_from_summaries = !!data[:excludeFromSummaries]
           @variations = data[:variations] || []
           @on = !!data[:on]
           fallthrough = data[:fallthrough] || {}
@@ -63,6 +67,12 @@ module LaunchDarkly
         attr_reader :version
         # @return [Boolean]
         attr_reader :deleted
+        # @return [MigrationSettings, nil]
+        attr_reader :migration_settings
+        # @return [Integer, nil]
+        attr_reader :sampling_ratio
+        # @return [Boolean, nil]
+        attr_reader :exclude_from_summaries
         # @return [Array]
         attr_reader :variations
         # @return [Boolean]
@@ -173,6 +183,19 @@ module LaunchDarkly
         attr_reader :variation_or_rollout
       end
 
+
+      class MigrationSettings
+        #
+        # @param check_ratio [Int, nil]
+        #
+        def initialize(check_ratio)
+          @check_ratio = check_ratio
+        end
+
+        # @return [Integer, nil]
+        attr_reader :check_ratio
+      end
+
       class VariationOrRollout
         def initialize(variation, rollout_data, flag = nil, errors_out = nil, description = nil)
           @variation = variation

data/lib/ldclient-rb/impl/sampler.rb

@@ -0,0 +1,25 @@
+module LaunchDarkly
+  module Impl
+    class Sampler
+      #
+      # @param random [Random]
+      #
+      def initialize(random)
+        @random = random
+      end
+
+      #
+      # @param ratio [Int]
+      #
+      # @return [Boolean]
+      #
+      def sample(ratio)
+        return false unless ratio.is_a? Integer
+        return false if ratio <= 0
+        return true if ratio == 1
+
+        @random.rand(1.0) < 1.0 / ratio
+      end
+    end
+  end
+end

data/lib/ldclient-rb/integrations/test_data/flag_builder.rb

@@ -43,6 +43,47 @@ module LaunchDarkly
           self
         end
 
+        #
+        # Set the migration related settings for this feature flag.
+        #
+        # The settings hash should be built using the {FlagMigrationSettingsBuilder}.
+        #
+        # @param settings [Hash]
+        # @return [FlagBuilder] the builder
+        #
+        def migration_settings(settings)
+          @migration_settings = settings
+          self
+        end
+
+        #
+        # Set the sampling ratio for this flag. This ratio is used to control the emission rate of feature, debug, and
+        # migration op events.
+        #
+        # General usage should not require interacting with this method.
+        #
+        # @param ratio [Integer]
+        # @return [FlagBuilder]
+        #
+        def sampling_ratio(ratio)
+          @sampling_ratio = ratio
+          self
+        end
+
+        #
+        # Set the option to exclude this flag from summary events. This is used to control the size of the summary event
+        # in the event certain flag payloads are large.
+        #
+        # General usage should not require interacting with this method.
+        #
+        # @param exclude [Boolean]
+        # @return [FlagBuilder]
+        #
+        def exclude_from_summaries(exclude)
+          @exclude_from_summaries = exclude
+          self
+        end
+
         #
         # Specifies the fallthrough variation. The fallthrough is the value
         # that is returned if targeting is on and the context was not matched by a more specific
@@ -128,11 +169,6 @@ module LaunchDarkly
           end
         end
 
-        #
-        # @deprecated Backwards compatibility alias for #variation_for_all
-        #
-        alias_method :variation_for_all_users, :variation_for_all
-
         #
         # Sets the flag to always return the specified variation value for all context.
         #
@@ -148,11 +184,6 @@ module LaunchDarkly
           variations(value).variation_for_all(0)
         end
 
-        #
-        # @deprecated Backwards compatibility alias for #value_for_all
-        #
-        alias_method :value_for_all_users, :value_for_all
-
         #
         # Sets the flag to return the specified variation for a specific context key when targeting
         # is on.
@@ -315,11 +346,6 @@ module LaunchDarkly
           self
         end
 
-        #
-        # @deprecated Backwards compatibility alias for #clear_targets
-        #
-        alias_method :clear_user_targets, :clear_targets
-
         #
         # Removes any existing rules from the flag.
         # This undoes the effect of methods like {#if_match}
@@ -376,6 +402,18 @@ module LaunchDarkly
             res[:fallthrough] = { variation: @fallthrough_variation }
           end
 
+          unless @migration_settings.nil?
+            res[:migration] = @migration_settings
+          end
+
+          unless @sampling_ratio.nil? || @sampling_ratio == 1
+            res[:samplingRatio] = @sampling_ratio
+          end
+
+          unless @exclude_from_summaries.nil? || !@exclude_from_summaries
+            res[:excludeFromSummaries] = @exclude_from_summaries
+          end
+
           unless @targets.nil?
             targets = []
             context_targets = []
@@ -403,6 +441,37 @@ module LaunchDarkly
           res
         end
 
+        #
+        # A builder for feature flag migration settings to be used with {FlagBuilder}.
+        #
+        # In the LaunchDarkly model, a flag can be a standard feature flag, or it can be a migration-related flag, in
+        # which case it has migration-specified related settings. These settings control things like the rate at which
+        # reads are tested for consistency between origins.
+        #
+        class FlagMigrationSettingsBuilder
+          def initialize()
+            @check_ratio = nil
+          end
+
+          #
+          # @param ratio [Integer]
+          # @return [FlagMigrationSettingsBuilder]
+          #
+          def check_ratio(ratio)
+            return unless ratio.is_a? Integer
+            @check_ratio = ratio
+            self
+          end
+
+          def build
+            return nil if @check_ratio.nil? || @check_ratio == 1
+
+            {
+              "checkRatio": @check_ratio,
+            }
+          end
+        end
+
         #
         # A builder for feature flag rules to be used with {FlagBuilder}.
         #