launchdarkly-server-sdk 8.8.3-java

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

@@ -0,0 +1,213 @@
+require 'ldclient-rb/impl/integrations/test_data/test_data_source'
+require 'ldclient-rb/impl/model/feature_flag'
+require 'ldclient-rb/impl/model/segment'
+require 'ldclient-rb/integrations/test_data/flag_builder'
+
+require 'concurrent/atomics'
+
+module LaunchDarkly
+  module Integrations
+    #
+    # A mechanism for providing dynamically updatable feature flag state in a simplified form to an SDK
+    # client in test scenarios.
+    #
+    # Unlike {LaunchDarkly::Integrations::FileData}, this mechanism does not use any external resources. It
+    # provides only the data that the application has put into it using the {#update} method.
+    #
+    # @example
+    #     td = LaunchDarkly::Integrations::TestData.data_source
+    #     td.update(td.flag("flag-key-1").variation_for_all(true))
+    #     config = LaunchDarkly::Config.new(data_source: td)
+    #     client = LaunchDarkly::LDClient.new('sdkKey', config)
+    #     # flags can be updated at any time:
+    #     td.update(td.flag("flag-key-2")
+    #                 .variation_for_key("user", some-user-key", true)
+    #                 .fallthrough_variation(false))
+    #
+    # The above example uses a simple boolean flag, but more complex configurations are possible using
+    # the methods of the {FlagBuilder} that is returned by {#flag}. {FlagBuilder}
+    # supports many of the ways a flag can be configured on the LaunchDarkly dashboard, but does not
+    # currently support 1. rule operators other than "in" and "not in", or 2. percentage rollouts.
+    #
+    # If the same `TestData` instance is used to configure multiple `LDClient` instances,
+    # any changes made to the data will propagate to all of the `LDClient`s.
+    #
+    # @since 6.3.0
+    #
+    class TestData
+      # Creates a new instance of the test data source.
+      #
+      # @return [TestData] a new configurable test data source
+      def self.data_source
+        self.new
+      end
+
+      # @private
+      def initialize
+        @flag_builders = Hash.new
+        @current_flags = Hash.new
+        @current_segments = Hash.new
+        @instances = Array.new
+        @instances_lock = Concurrent::ReadWriteLock.new
+        @lock = Concurrent::ReadWriteLock.new
+      end
+
+      #
+      # Called internally by the SDK to determine what arguments to pass to call
+      # You do not need to call this method.
+      #
+      # @private
+      def arity
+        2
+      end
+
+      #
+      # Called internally by the SDK to associate this test data source with an {@code LDClient} instance.
+      # You do not need to call this method.
+      #
+      # @private
+      def call(_, config)
+        impl = LaunchDarkly::Impl::Integrations::TestData::TestDataSource.new(config.feature_store, self)
+        @instances_lock.with_write_lock { @instances.push(impl) }
+        impl
+      end
+
+      #
+      # Creates or copies a {FlagBuilder} for building a test flag configuration.
+      #
+      # If this flag key has already been defined in this `TestData` instance, then the builder
+      # starts with the same configuration that was last provided for this flag.
+      #
+      # Otherwise, it starts with a new default configuration in which the flag has `true` and
+      # `false` variations, is `true` for all contexts when targeting is turned on and
+      # `false` otherwise, and currently has targeting turned on. You can change any of those
+      # properties, and provide more complex behavior, using the {FlagBuilder} methods.
+      #
+      # Once you have set the desired configuration, pass the builder to {#update}.
+      #
+      # @param key [String] the flag key
+      # @return [FlagBuilder] a flag configuration builder
+      #
+      def flag(key)
+        existing_builder = @lock.with_read_lock { @flag_builders[key] }
+        if existing_builder.nil?
+          FlagBuilder.new(key).boolean_flag
+        else
+          existing_builder.clone
+        end
+      end
+
+      #
+      # Updates the test data with the specified flag configuration.
+      #
+      # This has the same effect as if a flag were added or modified on the LaunchDarkly dashboard.
+      # It immediately propagates the flag change to any `LDClient` instance(s) that you have
+      # already configured to use this `TestData`. If no `LDClient` has been started yet,
+      # it simply adds this flag to the test data which will be provided to any `LDClient` that
+      # you subsequently configure.
+      #
+      # Any subsequent changes to this {FlagBuilder} instance do not affect the test data,
+      # unless you call {#update} again.
+      #
+      # @param flag_builder [FlagBuilder] a flag configuration builder
+      # @return [TestData] the TestData instance
+      #
+      def update(flag_builder)
+        new_flag = nil
+        @lock.with_write_lock do
+          @flag_builders[flag_builder.key] = flag_builder
+          version = 0
+          flag_key = flag_builder.key.to_sym
+          if @current_flags[flag_key]
+            version = @current_flags[flag_key][:version]
+          end
+          new_flag = Impl::Model.deserialize(FEATURES, flag_builder.build(version+1))
+          @current_flags[flag_key] = new_flag
+        end
+        update_item(FEATURES, new_flag)
+        self
+      end
+
+      #
+      # Copies a full feature flag data model object into the test data.
+      #
+      # It immediately propagates the flag change to any `LDClient` instance(s) that you have already
+      # configured to use this `TestData`. If no `LDClient` has been started yet, it simply adds
+      # this flag to the test data which will be provided to any LDClient that you subsequently
+      # configure.
+      #
+      # Use this method if you need to use advanced flag configuration properties that are not supported by
+      # the simplified {FlagBuilder} API. Otherwise it is recommended to use the regular {flag}/{update}
+      # mechanism to avoid dependencies on details of the data model.
+      #
+      # You cannot make incremental changes with {flag}/{update} to a flag that has been added in this way;
+      # you can only replace it with an entirely new flag configuration.
+      #
+      # @param flag [Hash] the flag configuration
+      # @return [TestData] the TestData instance
+      #
+      def use_preconfigured_flag(flag)
+        use_preconfigured_item(FEATURES, flag, @current_flags)
+      end
+
+      #
+      # Copies a full segment data model object into the test data.
+      #
+      # It immediately propagates the change to any `LDClient` instance(s) that you have already
+      # configured to use this `TestData`. If no `LDClient` has been started yet, it simply adds
+      # this segment to the test data which will be provided to any LDClient that you subsequently
+      # configure.
+      #
+      # This method is currently the only way to inject segment data, since there is no builder
+      # API for segments. It is mainly intended for the SDK's own tests of segment functionality,
+      # since application tests that need to produce a desired evaluation state could do so more easily
+      # by just setting flag values.
+      #
+      # @param segment [Hash] the segment configuration
+      # @return [TestData] the TestData instance
+      #
+      def use_preconfigured_segment(segment)
+        use_preconfigured_item(SEGMENTS, segment, @current_segments)
+      end
+
+      private def use_preconfigured_item(kind, item, current)
+        item = Impl::Model.deserialize(kind, item)
+        key = item.key.to_sym
+        @lock.with_write_lock do
+          old_item = current[key]
+          unless old_item.nil?
+            data = item.as_json
+            data[:version] = old_item.version + 1
+            item = Impl::Model.deserialize(kind, data)
+          end
+          current[key] = item
+        end
+        update_item(kind, item)
+        self
+      end
+
+      private def update_item(kind, item)
+        @instances_lock.with_read_lock do
+          @instances.each do | instance |
+            instance.upsert(kind, item)
+          end
+        end
+      end
+
+      # @private
+      def make_init_data
+        @lock.with_read_lock do
+          {
+            FEATURES => @current_flags.clone,
+            SEGMENTS => @current_segments.clone,
+          }
+        end
+      end
+
+      # @private
+      def closed_instance(instance)
+        @instances_lock.with_write_lock { @instances.delete(instance) }
+      end
+    end
+  end
+end

data/lib/ldclient-rb/integrations/util/store_wrapper.rb

@@ -0,0 +1,246 @@
+require "concurrent/atomics"
+
+require "ldclient-rb/expiring_cache"
+
+module LaunchDarkly
+  module Integrations
+    #
+    # Support code that may be helpful in creating integrations.
+    #
+    # @since 5.5.0
+    #
+    module Util
+      #
+      # CachingStoreWrapper is a partial implementation of the {LaunchDarkly::Interfaces::FeatureStore}
+      # pattern that delegates part of its behavior to another object, while providing optional caching
+      # behavior and other logic that would otherwise be repeated in every feature store implementation.
+      # This makes it easier to create new database integrations by implementing only the database-specific
+      # logic.
+      #
+      # The mixin {FeatureStoreCore} describes the methods that need to be supported by the inner
+      # implementation object.
+      #
+      class CachingStoreWrapper
+        include LaunchDarkly::Interfaces::FeatureStore
+
+        #
+        # Creates a new store wrapper instance.
+        #
+        # @param core [Object]  an object that implements the {FeatureStoreCore} methods
+        # @param opts [Hash]  a hash that may include cache-related options; all others will be ignored
+        # @option opts [Float] :expiration (15)  cache TTL; zero means no caching
+        # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
+        #
+        def initialize(core, opts)
+          @core = core
+
+          expiration_seconds = opts[:expiration] || 15
+          if expiration_seconds > 0
+            capacity = opts[:capacity] || 1000
+            @cache = ExpiringCache.new(capacity, expiration_seconds)
+          else
+            @cache = nil
+          end
+
+          @inited = Concurrent::AtomicBoolean.new(false)
+          @has_available_method = @core.respond_to? :available?
+        end
+
+        def monitoring_enabled?
+          @has_available_method
+        end
+
+        def available?
+          return false unless @has_available_method
+
+          @core.available?
+        end
+
+        def init(all_data)
+          @core.init_internal(all_data)
+          @inited.make_true
+
+          unless @cache.nil?
+            @cache.clear
+            all_data.each do |kind, items|
+              @cache[kind] = items_if_not_deleted(items)
+              items.each do |key, item|
+                @cache[item_cache_key(kind, key)] = [item]
+              end
+            end
+          end
+        end
+
+        def get(kind, key)
+          unless @cache.nil?
+            cache_key = item_cache_key(kind, key)
+            cached = @cache[cache_key] # note, item entries in the cache are wrapped in an array so we can cache nil values
+            return item_if_not_deleted(cached[0]) unless cached.nil?
+          end
+
+          item = @core.get_internal(kind, key)
+
+          unless @cache.nil?
+            @cache[cache_key] = [item]
+          end
+
+          item_if_not_deleted(item)
+        end
+
+        def all(kind)
+          unless @cache.nil?
+            items = @cache[all_cache_key(kind)]
+            return items unless items.nil?
+          end
+
+          items = items_if_not_deleted(@core.get_all_internal(kind))
+          @cache[all_cache_key(kind)] = items unless @cache.nil?
+          items
+        end
+
+        def upsert(kind, item)
+          new_state = @core.upsert_internal(kind, item)
+
+          unless @cache.nil?
+            @cache[item_cache_key(kind, item[:key])] = [new_state]
+            @cache.delete(all_cache_key(kind))
+          end
+        end
+
+        def delete(kind, key, version)
+          upsert(kind, { key: key, version: version, deleted: true })
+        end
+
+        def initialized?
+          return true if @inited.value
+
+          if @cache.nil?
+            result = @core.initialized_internal?
+          else
+            result = @cache[inited_cache_key]
+            if result.nil?
+              result = @core.initialized_internal?
+              @cache[inited_cache_key] = result
+            end
+          end
+
+          @inited.make_true if result
+          result
+        end
+
+        def stop
+          @core.stop
+        end
+
+        private
+
+        # We use just one cache for 3 kinds of objects. Individual entities use a key like 'features:my-flag'.
+        def item_cache_key(kind, key)
+          kind[:namespace] + ":" + key.to_s
+        end
+
+        # The result of a call to get_all_internal is cached using the "kind" object as a key.
+        def all_cache_key(kind)
+          kind
+        end
+
+        # The result of initialized_internal? is cached using this key.
+        def inited_cache_key
+          "$inited"
+        end
+
+        def item_if_not_deleted(item)
+          (item.nil? || item[:deleted]) ? nil : item
+        end
+
+        def items_if_not_deleted(items)
+          items.select { |key, item| !item[:deleted] }
+        end
+      end
+
+      #
+      # This module describes the methods that you must implement on your own object in order to
+      # use {CachingStoreWrapper}.
+      #
+      module FeatureStoreCore
+        #
+        # Initializes the store. This is the same as {LaunchDarkly::Interfaces::FeatureStore#init},
+        # but the wrapper will take care of updating the cache if caching is enabled.
+        #
+        # If possible, the store should update the entire data set atomically. If that is not possible,
+        # it should iterate through the outer hash and then the inner hash using the existing iteration
+        # order of those hashes (the SDK will ensure that the items were inserted into the hashes in
+        # the correct order), storing each item, and then delete any leftover items at the very end.
+        #
+        # @param all_data [Hash]  a hash where each key is one of the data kind objects, and each
+        #   value is in turn a hash of string keys to entities
+        # @return [void]
+        #
+        def init_internal(all_data)
+        end
+
+        #
+        # Retrieves a single entity. This is the same as {LaunchDarkly::Interfaces::FeatureStore#get}
+        # except that 1. the wrapper will take care of filtering out deleted entities by checking the
+        # `:deleted` property, so you can just return exactly what was in the data store, and 2. the
+        # wrapper will take care of checking and updating the cache if caching is enabled.
+        #
+        # @param kind [Object]  the kind of entity to get
+        # @param key [String]  the unique key of the entity to get
+        # @return [Hash]  the entity; nil if the key was not found
+        #
+        def get_internal(kind, key)
+        end
+
+        #
+        # Retrieves all entities of the specified kind. This is the same as {LaunchDarkly::Interfaces::FeatureStore#all}
+        # except that 1. the wrapper will take care of filtering out deleted entities by checking the
+        # `:deleted` property, so you can just return exactly what was in the data store, and 2. the
+        # wrapper will take care of checking and updating the cache if caching is enabled.
+        #
+        # @param kind [Object]  the kind of entity to get
+        # @return [Hash]  a hash where each key is the entity's `:key` property and each value
+        #   is the entity
+        #
+        def get_all_internal(kind)
+        end
+
+        #
+        # Attempts to add or update an entity. This is the same as {LaunchDarkly::Interfaces::FeatureStore#upsert}
+        # except that 1. the wrapper will take care of updating the cache if caching is enabled, and 2.
+        # the method is expected to return the final state of the entity (i.e. either the `item`
+        # parameter if the update succeeded, or the previously existing entity in the store if the
+        # update failed; this is used for the caching logic).
+        #
+        # Note that FeatureStoreCore does not have a `delete` method. This is because {CachingStoreWrapper}
+        # implements `delete` by simply calling `upsert` with an item whose `:deleted` property is true.
+        #
+        # @param kind [Object]  the kind of entity to add or update
+        # @param item [Hash]  the entity to add or update
+        # @return [Hash]  the entity as it now exists in the store after the update
+        #
+        def upsert_internal(kind, item)
+        end
+
+        #
+        # Checks whether this store has been initialized. This is the same as
+        # {LaunchDarkly::Interfaces::FeatureStore#initialized?} except that there is less of a concern
+        # for efficiency, because the wrapper will use caching and memoization in order to call the method
+        # as little as possible.
+        #
+        # @return [Boolean]  true if the store is in an initialized state
+        #
+        def initialized_internal?
+        end
+
+        #
+        # Performs any necessary cleanup to shut down the store when the client is being shut down.
+        #
+        # @return [void]
+        #
+        def stop
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-rb/integrations.rb

@@ -0,0 +1,6 @@
+require "ldclient-rb/integrations/consul"
+require "ldclient-rb/integrations/dynamodb"
+require "ldclient-rb/integrations/file_data"
+require "ldclient-rb/integrations/redis"
+require "ldclient-rb/integrations/test_data"
+require "ldclient-rb/integrations/util/store_wrapper"