launchdarkly-server-sdk 8.3.1 → 8.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2582d6e0bd754b6fbb46d591713cb9b6d3784ae991a498dfa0f810aa079c491e
-  data.tar.gz: 68c0369beb8e2bd6f3a865129591a392511a82f85b22fda5b8a8c3c7161f4fa1
+  metadata.gz: 6067b2e1ab38ffb622a683a63206d485bd13744f361d99f89de467b5f1bc0c9e
+  data.tar.gz: 28999c77f6007effa021c4d88a99d3b6ad7ddd951d0e93449ee25276b311290b
 SHA512:
-  metadata.gz: 0516d7e11b48b9d582878270ff533138b73f9fdfb8d89a9dc6470c0aeff8d71a9139d5e7b77a4b5eb0e7c6083c33446ecdf9d57b394cfb650ac53426fee2cd06
-  data.tar.gz: 71f2eb165af4d1ef812f1360f326b2dfefe6be266c4d476737943661a3c2534f7f275bb02245e4718c653aaa2df3e07675af3a3e3ca1f451cfb045d2bac506c8
+  metadata.gz: 9f4e045335066941a471cb09a183867318256c093449992b966724b7b5a0f12e8caae2b73ec4beda03c8732130e0891827209ddc22f42bb7de50267135ee3ed6
+  data.tar.gz: e949b6e9d82371ef4a9d6e0d412b6979dc0e1963336fde18c15b6bffea1b023d0ab885cc12fc8a73522cbc59a1174b5ca8c60bbe84fada1aaf6671acbaf8e9b2

data/lib/ldclient-rb/config.rb

@@ -43,6 +43,7 @@ module LaunchDarkly
     # @option opts [BigSegmentsConfig] :big_segments See {#big_segments}.
     # @option opts [Hash] :application See {#application}
     # @option opts [String] :payload_filter_key See {#payload_filter_key}
+    # @option hooks [Array<Interfaces::Hooks::Hook]
     #
     def initialize(opts = {})
       @base_uri = (opts[:base_uri] || Config.default_base_uri).chomp("/")
@@ -75,6 +76,7 @@ module LaunchDarkly
       @big_segments = opts[:big_segments] || BigSegmentsConfig.new(store: nil)
       @application = LaunchDarkly::Impl::Util.validate_application_info(opts[:application] || {}, @logger)
       @payload_filter_key = opts[:payload_filter_key]
+      @hooks = (opts[:hooks] || []).keep_if { |hook| hook.is_a? Interfaces::Hooks::Hook }
       @data_source_update_sink = nil
     end
 
@@ -372,6 +374,17 @@ module LaunchDarkly
     #
     attr_reader :socket_factory
 
+    #
+    # Initial set of hooks for the client.
+    #
+    # Hooks provide entrypoints which allow for observation of SDK functions.
+    #
+    # LaunchDarkly provides integration packages, and most applications will not
+    # need to implement their own hooks. Refer to the `launchdarkly-server-sdk-otel` gem
+    # for instrumentation.
+    #
+    attr_reader :hooks
+
     #
     # The default LaunchDarkly client configuration. This configuration sets
     # reasonable defaults for most users.

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

@@ -0,0 +1,34 @@
+module LaunchDarkly
+  module Impl
+    #
+    # Simple helper class for returning formatted data.
+    #
+    # The variation methods make use of the new hook support. Those methods all need to return an evaluation detail, and
+    # some other unstructured bit of data.
+    #
+    class EvaluationWithHookResult
+      #
+      # Return the evaluation detail that was generated as part of the evaluation.
+      #
+      # @return [LaunchDarkly::EvaluationDetail]
+      #
+      attr_reader :evaluation_detail
+
+      #
+      # All purpose container for additional return values from the wrapping method
+      #
+      # @return [any]
+      #
+      attr_reader :results
+
+      #
+      # @param evaluation_detail [LaunchDarkly::EvaluationDetail]
+      # @param results [any]
+      #
+      def initialize(evaluation_detail, results = nil)
+        @evaluation_detail = evaluation_detail
+        @results = results
+      end
+    end
+  end
+end

data/lib/ldclient-rb/interfaces.rb

@@ -885,5 +885,90 @@ module LaunchDarkly
         end
       end
     end
+
+    module Hooks
+      #
+      # Mixin for extending SDK functionality via hooks.
+      #
+      # All provided hook implementations **MUST** include this mixin. Hooks without this mixin will be ignored.
+      #
+      # This mixin includes default implementations for all hook handlers. This allows LaunchDarkly to expand the list
+      # of hook handlers without breaking customer integrations.
+      #
+      module Hook
+        #
+        # Get metadata about the hook implementation.
+        #
+        # @return [Metadata]
+        #
+        def metadata
+          Metadata.new('UNDEFINED')
+        end
+
+        #
+        # The before method is called during the execution of a variation method before the flag value has been
+        # determined. The method is executed synchronously.
+        #
+        # @param evaluation_series_context [EvaluationSeriesContext] Contains information about the evaluation being
+        # performed. This is not mutable.
+        # @param data [Hash] A record associated with each stage of hook invocations. Each stage is called with the data
+        # of the previous stage for a series. The input record should not be modified.
+        # @return [Hash] Data to use when executing the next state of the hook in the evaluation series.
+        #
+        def before_evaluation(evaluation_series_context, data)
+          data
+        end
+
+        #
+        # The after method is called during the execution of the variation method after the flag value has been
+        # determined. The method is executed synchronously.
+        #
+        # @param evaluation_series_context [EvaluationSeriesContext] Contains read-only information about the evaluation
+        # being performed.
+        # @param data [Hash] A record associated with each stage of hook invocations. Each stage is called with the data
+        # of the previous stage for a series.
+        # @param detail [LaunchDarkly::EvaluationDetail] The result of the evaluation. This value should not be
+        # modified.
+        # @return [Hash] Data to use when executing the next state of the hook in the evaluation series.
+        #
+        def after_evaluation(evaluation_series_context, data, detail)
+          data
+        end
+      end
+
+      #
+      # Metadata data class used for annotating hook implementations.
+      #
+      class Metadata
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+      end
+
+      #
+      # Contextual information that will be provided to handlers during evaluation series.
+      #
+      class EvaluationSeriesContext
+        attr_reader :key
+        attr_reader :context
+        attr_reader :default_value
+        attr_reader :method
+
+        #
+        # @param key [String]
+        # @param context [LaunchDarkly::LDContext]
+        # @param default_value [any]
+        # @param method [Symbol]
+        #
+        def initialize(key, context, default_value, method)
+          @key = key
+          @context = context
+          @default_value = default_value
+          @method = method
+        end
+      end
+    end
   end
 end

data/lib/ldclient-rb/ldclient.rb

@@ -4,9 +4,11 @@ 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"
@@ -54,6 +56,7 @@ module LaunchDarkly
       end
 
       @sdk_key = sdk_key
+      @hooks = Concurrent::Array.new(config.hooks)
 
       @shared_executor = Concurrent::SingleThreadExecutor.new
 
@@ -131,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.
     #
@@ -198,8 +218,13 @@ module LaunchDarkly
     # @return the variation for the provided context, or the default value if there's an error
     #
     def variation(key, context, default)
-      detail, _, _, = variation_with_flag(key, context, default)
-      detail.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
 
     #
@@ -226,8 +251,118 @@ module LaunchDarkly
     # @return [EvaluationDetail] an object describing the result
     #
     def variation_detail(key, context, default)
-      detail, _, _ = evaluate_internal(key, context, default, true)
-      detail
+      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
 
     #
@@ -249,20 +384,24 @@ module LaunchDarkly
       end
 
       context = Impl::Context::make_context(context)
-      detail, flag, _ = variation_with_flag(key, context, default_stage.to_s)
+      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
+        stage = detail.value
+        stage = stage.to_sym if stage.respond_to? :to_sym
 
-      if Migrations::VALID_STAGES.include?(stage)
+        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)
-        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)
+        LaunchDarkly::Impl::EvaluationWithHookResult.new(detail, {stage: default_stage, tracker: tracker})
+      end
 
-      [default_stage, tracker]
+      [result.results[:stage], result.results[:tracker]]
     end
 
     #
@@ -502,7 +641,7 @@ module LaunchDarkly
 
     #
     # @param key [String]
-    # @param context [Hash, LDContext]
+    # @param context [LDContext]
     # @param default [Object]
     #
     # @return [Array<EvaluationDetail, [LaunchDarkly::Impl::Model::FeatureFlag, nil], [String, nil]>]
@@ -513,7 +652,7 @@ module LaunchDarkly
 
     #
     # @param key [String]
-    # @param context [Hash, LDContext]
+    # @param context [LDContext]
     # @param default [Object]
     # @param with_reasons [Boolean]
     #
@@ -530,7 +669,6 @@ module LaunchDarkly
         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)

data/lib/ldclient-rb/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: launchdarkly-server-sdk
 version: !ruby/object:Gem::Version
-  version: 8.3.1
+  version: 8.4.0
 platform: ruby
 authors:
 - LaunchDarkly
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-03-28 00:00:00.000000000 Z
+date: 2024-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -295,6 +295,7 @@ files:
 - lib/ldclient-rb/impl/data_store.rb
 - lib/ldclient-rb/impl/dependency_tracker.rb
 - lib/ldclient-rb/impl/diagnostic_events.rb
+- lib/ldclient-rb/impl/evaluation_with_hook_result.rb
 - lib/ldclient-rb/impl/evaluator.rb
 - lib/ldclient-rb/impl/evaluator_bucketing.rb
 - lib/ldclient-rb/impl/evaluator_helpers.rb