launchdarkly-server-sdk 7.0.2 → 8.4.2

data/lib/ldclient-rb/ldclient.rb

@@ -1,9 +1,17 @@
 require "ldclient-rb/impl/big_segments"
+require "ldclient-rb/impl/broadcaster"
+require "ldclient-rb/impl/data_source"
+require "ldclient-rb/impl/data_store"
 require "ldclient-rb/impl/diagnostic_events"
 require "ldclient-rb/impl/evaluator"
+require "ldclient-rb/impl/evaluation_with_hook_result"
+require "ldclient-rb/impl/flag_tracker"
 require "ldclient-rb/impl/store_client_wrapper"
+require "ldclient-rb/impl/migrations/tracker"
+require "concurrent"
 require "concurrent/atomics"
 require "digest/sha1"
+require "forwardable"
 require "logger"
 require "benchmark"
 require "json"
@@ -16,6 +24,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,
@@ -44,16 +56,24 @@ module LaunchDarkly
       end
 
       @sdk_key = sdk_key
+      @hooks = Concurrent::Array.new(config.hooks)
+
+      @shared_executor = Concurrent::SingleThreadExecutor.new
+
+      data_store_broadcaster = LaunchDarkly::Impl::Broadcaster.new(@shared_executor, config.logger)
+      store_sink = LaunchDarkly::Impl::DataStore::UpdateSink.new(data_store_broadcaster)
 
       # We need to wrap the feature store object with a FeatureStoreClientWrapper in order to add
       # some necessary logic around updates. Unfortunately, we have code elsewhere that accesses
       # the feature store through the Config object, so we need to make a new Config that uses
       # the wrapped store.
-      @store = Impl::FeatureStoreClientWrapper.new(config.feature_store)
+      @store = Impl::FeatureStoreClientWrapper.new(config.feature_store, store_sink, config.logger)
       updated_config = config.clone
       updated_config.instance_variable_set(:@feature_store, @store)
       @config = updated_config
 
+      @data_store_status_provider = LaunchDarkly::Impl::DataStore::StatusProvider.new(@store, store_sink)
+
       @big_segment_store_manager = Impl::BigSegmentStoreManager.new(config.big_segments, @config.logger)
       @big_segment_store_status_provider = @big_segment_store_manager.status_provider
 
@@ -76,9 +96,20 @@ module LaunchDarkly
 
       if @config.use_ldd?
         @config.logger.info { "[LDClient] Started LaunchDarkly Client in LDD mode" }
+        @data_source = NullUpdateProcessor.new
         return  # requestor and update processor are not used in this mode
       end
 
+      flag_tracker_broadcaster = LaunchDarkly::Impl::Broadcaster.new(@shared_executor, @config.logger)
+      @flag_tracker = LaunchDarkly::Impl::FlagTracker.new(flag_tracker_broadcaster, lambda { |key, context| variation(key, context, nil) })
+
+      data_source_broadcaster = LaunchDarkly::Impl::Broadcaster.new(@shared_executor, @config.logger)
+
+      # Make the update sink available on the config so that our data source factory can access the sink with a shared executor.
+      @config.data_source_update_sink = LaunchDarkly::Impl::DataSource::UpdateSink.new(@store, data_source_broadcaster, flag_tracker_broadcaster)
+
+      @data_source_status_provider = LaunchDarkly::Impl::DataSource::StatusProvider.new(data_source_broadcaster, @config.data_source_update_sink)
+
       data_source_or_factory = @config.data_source || self.method(:create_default_data_source)
       if data_source_or_factory.respond_to? :call
         # Currently, data source factories take two parameters unless they need to be aware of diagnostic_accumulator, in
@@ -103,6 +134,23 @@ module LaunchDarkly
       end
     end
 
+    #
+    # Add a hook to the client. In order to register a hook before the client starts, please use the `hooks` property of
+    # {#LDConfig}.
+    #
+    # Hooks provide entrypoints which allow for observation of SDK functions.
+    #
+    # @param hook [Interfaces::Hooks::Hook]
+    #
+    def add_hook(hook)
+      unless hook.is_a?(Interfaces::Hooks::Hook)
+        @config.logger.error { "[LDClient] Attempted to add a hook that does not include the LaunchDarkly::Intefaces::Hooks::Hook mixin. Ignoring." }
+        return
+      end
+
+      @hooks.push(hook)
+    end
+
     #
     # Tells the client that all pending analytics events should be delivered as soon as possible.
     #
@@ -127,7 +175,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
@@ -167,10 +215,16 @@ 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
+      context = Impl::Context::make_context(context)
+      result = evaluate_with_hooks(key, context, default, :variation) do
+        detail, _, _ = variation_with_flag(key, context, default)
+        LaunchDarkly::Impl::EvaluationWithHookResult.new(detail)
+      end
+
+      result.evaluation_detail.value
     end
 
     #
@@ -197,7 +251,157 @@ module LaunchDarkly
     # @return [EvaluationDetail] an object describing the result
     #
     def variation_detail(key, context, default)
-      evaluate_internal(key, context, default, true)
+      context = Impl::Context::make_context(context)
+      result = evaluate_with_hooks(key, context, default, :variation_detail) do
+        detail, _, _ = evaluate_internal(key, context, default, true)
+        LaunchDarkly::Impl::EvaluationWithHookResult.new(detail)
+      end
+
+      result.evaluation_detail
+    end
+
+    #
+    # evaluate_with_hook will run the provided block, wrapping it with evaluation hook support.
+    #
+    # Example:
+    #
+    # ```ruby
+    # evaluate_with_hooks(key, context, default, method) do
+    #   puts 'This is being wrapped with evaluation hooks'
+    # end
+    # ```
+    #
+    # @param key [String]
+    # @param context [LDContext]
+    # @param default [any]
+    # @param method [Symbol]
+    # @param &block [#call] Implicit passed block
+    #
+    # @return [LaunchDarkly::Impl::EvaluationWithHookResult]
+    #
+    private def evaluate_with_hooks(key, context, default, method)
+      return yield if @hooks.empty?
+
+      hooks, evaluation_series_context = prepare_hooks(key, context, default, method)
+      hook_data = execute_before_evaluation(hooks, evaluation_series_context)
+      evaluation_result = yield
+      execute_after_evaluation(hooks, evaluation_series_context, hook_data, evaluation_result.evaluation_detail)
+
+      evaluation_result
+    end
+
+    #
+    # Execute the :before_evaluation stage of the evaluation series.
+    #
+    # This method will return the results of each hook, indexed into an array in the same order as the hooks. If a hook
+    # raised an uncaught exception, the value will be nil.
+    #
+    # @param hooks [Array<Interfaces::Hooks::Hook>]
+    # @param evaluation_series_context [EvaluationSeriesContext]
+    #
+    # @return [Array<any>]
+    #
+    private def execute_before_evaluation(hooks, evaluation_series_context)
+      hooks.map do |hook|
+        try_execute_stage(:before_evaluation, hook.metadata.name) do
+          hook.before_evaluation(evaluation_series_context, {})
+        end
+      end
+    end
+
+    #
+    # Execute the :after_evaluation stage of the evaluation series.
+    #
+    # This method will return the results of each hook, indexed into an array in the same order as the hooks. If a hook
+    # raised an uncaught exception, the value will be nil.
+    #
+    # @param hooks [Array<Interfaces::Hooks::Hook>]
+    # @param evaluation_series_context [EvaluationSeriesContext]
+    # @param hook_data [Array<any>]
+    # @param evaluation_detail [EvaluationDetail]
+    #
+    # @return [Array<any>]
+    #
+    private def execute_after_evaluation(hooks, evaluation_series_context, hook_data, evaluation_detail)
+      hooks.zip(hook_data).reverse.map do |(hook, data)|
+        try_execute_stage(:after_evaluation, hook.metadata.name) do
+          hook.after_evaluation(evaluation_series_context, data, evaluation_detail)
+        end
+      end
+    end
+
+    #
+    # Try to execute the provided block. If execution raises an exception, catch and log it, then move on with
+    # execution.
+    #
+    # @return [any]
+    #
+    private def try_execute_stage(method, hook_name)
+      begin
+        yield
+      rescue => e
+        @config.logger.error { "[LDClient] An error occurred in #{method} of the hook #{hook_name}: #{e}" }
+        nil
+      end
+    end
+
+    #
+    # Return a copy of the existing hooks and a few instance of the EvaluationSeriesContext used for the evaluation series.
+    #
+    # @param key [String]
+    # @param context [LDContext]
+    # @param default [any]
+    # @param method [Symbol]
+    # @return [Array[Array<Interfaces::Hooks::Hook>, Interfaces::Hooks::EvaluationSeriesContext]]
+    #
+    private def prepare_hooks(key, context, default, method)
+      # Copy the hooks to use a consistent set during the evaluation series.
+      #
+      # Hooks can be added and we want to ensure all correct stages for a given hook execute. For example, we do not
+      # want to trigger the after_evaluation method without also triggering the before_evaluation method.
+      hooks = @hooks.dup
+      evaluation_series_context = Interfaces::Hooks::EvaluationSeriesContext.new(key, context, default, method)
+
+      [hooks, evaluation_series_context]
+    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)
+      result = evaluate_with_hooks(key, context, default_stage, :migration_variation) do
+        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)
+          next LaunchDarkly::Impl::EvaluationWithHookResult.new(detail, {stage: stage, tracker: 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)
+
+        LaunchDarkly::Impl::EvaluationWithHookResult.new(detail, {stage: default_stage, tracker: tracker})
+      end
+
+      [result.results[:stage], result.results[:tracker]]
     end
 
     #
@@ -260,6 +464,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
@@ -345,16 +575,53 @@ module LaunchDarkly
       @event_processor.stop
       @big_segment_store_manager.stop
       @store.stop
+      @shared_executor.shutdown
     end
 
     #
     # Returns an interface for tracking the status of a Big Segment store.
     #
-    # The {BigSegmentStoreStatusProvider} has methods for checking whether the Big Segment store
+    # The {Interfaces::BigSegmentStoreStatusProvider} has methods for checking whether the Big Segment store
     # is (as far as the SDK knows) currently operational and tracking changes in this status.
     #
     attr_reader :big_segment_store_status_provider
 
+    #
+    # Returns an interface for tracking the status of a persistent data store.
+    #
+    # The {LaunchDarkly::Interfaces::DataStore::StatusProvider} has methods for
+    # checking whether the data store is (as far as the SDK knows) currently
+    # operational, tracking changes in this status, and getting cache
+    # statistics. These are only relevant for a persistent data store; if you
+    # are using an in-memory data store, then this method will return a stub
+    # object that provides no information.
+    #
+    # @return [LaunchDarkly::Interfaces::DataStore::StatusProvider]
+    #
+    attr_reader :data_store_status_provider
+
+    #
+    # Returns an interface for tracking the status of the data source.
+    #
+    # The data source is the mechanism that the SDK uses to get feature flag
+    # configurations, such as a streaming connection (the default) or poll
+    # requests. The {LaunchDarkly::Interfaces::DataSource::StatusProvider} has
+    # methods for checking whether the data source is (as far as the SDK knows)
+    # currently operational and tracking changes in this status.
+    #
+    # @return [LaunchDarkly::Interfaces::DataSource::StatusProvider]
+    #
+    attr_reader :data_source_status_provider
+
+    #
+    # Returns an interface for tracking changes in feature flag configurations.
+    #
+    # The {LaunchDarkly::Interfaces::FlagTracker} contains methods for
+    # requesting notifications about feature flag changes using an event
+    # listener model.
+    #
+    attr_reader :flag_tracker
+
     private
 
     def create_default_data_source(sdk_key, config, diagnostic_accumulator)
@@ -372,24 +639,40 @@ module LaunchDarkly
       end
     end
 
-    # @param context [Hash, LDContext]
-    # @return [EvaluationDetail]
+    #
+    # @param key [String]
+    # @param context [LDContext]
+    # @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 [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 flag evaluation (#{context.error}); returning default value" }
+        @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?
@@ -399,17 +682,21 @@ 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
 
-      feature = @store.get(FEATURES, key)
+      begin
+        feature = @store.get(FEATURES, key)
+      rescue
+        # Ignored
+      end
 
       if feature.nil?
         @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
@@ -424,12 +711,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
 
@@ -445,7 +732,9 @@ module LaunchDarkly
         default,
         add_experiment_data || flag[:trackEvents] || false,
         flag[:debugEventsUntilDate],
-        nil
+        nil,
+        flag[:samplingRatio],
+        !!flag[:excludeFromSummaries]
       )
     end
 
@@ -461,13 +750,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
 
     #
@@ -479,7 +770,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)