launchdarkly-server-sdk 5.5.7

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

@@ -0,0 +1,47 @@
+require "ldclient-rb/interfaces"
+require "ldclient-rb/impl/store_data_set_sorter"
+
+module LaunchDarkly
+  module Impl
+    #
+    # Provides additional behavior that the client requires before or after feature store operations.
+    # Currently this just means sorting the data set for init(). In the future we may also use this
+    # to provide an update listener capability.
+    #
+    class FeatureStoreClientWrapper
+      include Interfaces::FeatureStore
+
+      def initialize(store)
+        @store = store
+      end
+
+      def init(all_data)
+        @store.init(FeatureStoreDataSetSorter.sort_all_collections(all_data))
+      end
+
+      def get(kind, key)
+        @store.get(kind, key)
+      end
+
+      def all(kind)
+        @store.all(kind)
+      end
+
+      def upsert(kind, item)
+        @store.upsert(kind, item)
+      end
+
+      def delete(kind, key, version)
+        @store.delete(kind, key, version)
+      end
+
+      def initialized?
+        @store.initialized?
+      end
+
+      def stop
+        @store.stop
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+
+module LaunchDarkly
+  module Impl
+    #
+    # Implements a dependency graph ordering for data to be stored in a feature store. We must use this
+    # on every data set that will be passed to the feature store's init() method.
+    #
+    class FeatureStoreDataSetSorter
+      #
+      # Returns a copy of the input hash that has the following guarantees: the iteration order of the outer
+      # hash will be in ascending order by the VersionDataKind's :priority property (if any), and for each
+      # data kind that has a :get_dependency_keys function, the inner hash will have an iteration order
+      # where B is before A if A has a dependency on B.
+      #
+      # This implementation relies on the fact that hashes in Ruby have an iteration order that is the same
+      # as the insertion order. Also, due to the way we deserialize JSON received from LaunchDarkly, the
+      # keys in the inner hash will always be symbols.
+      #
+      def self.sort_all_collections(all_data)
+        outer_hash = {}
+        kinds = all_data.keys.sort_by { |k|
+          k[:priority].nil? ? k[:namespace].length : k[:priority]  # arbitrary order if priority is unknown
+        }
+        kinds.each do |kind|
+          items = all_data[kind]
+          outer_hash[kind] = self.sort_collection(kind, items)
+        end
+        outer_hash
+      end
+
+      def self.sort_collection(kind, input)
+        dependency_fn = kind[:get_dependency_keys]
+        return input if dependency_fn.nil? || input.empty?
+        remaining_items = input.clone
+        items_out = {}
+        while !remaining_items.empty?
+          # pick a random item that hasn't been updated yet
+          key, item = remaining_items.first
+          self.add_with_dependencies_first(item, dependency_fn, remaining_items, items_out)
+        end
+        items_out
+      end
+
+      def self.add_with_dependencies_first(item, dependency_fn, remaining_items, items_out)
+        item_key = item[:key].to_sym
+        remaining_items.delete(item_key)  # we won't need to visit this item again
+        dependency_fn.call(item).each do |dep_key|
+          dep_item = remaining_items[dep_key.to_sym]
+          self.add_with_dependencies_first(dep_item, dependency_fn, remaining_items, items_out) if !dep_item.nil?
+        end
+        items_out[item_key] = item
+      end
+    end
+  end
+end

data/lib/ldclient-rb/in_memory_store.rb

@@ -0,0 +1,100 @@
+require "concurrent/atomics"
+
+module LaunchDarkly
+
+  # These constants denote the types of data that can be stored in the feature store.  If
+  # we add another storable data type in the future, as long as it follows the same pattern
+  # (having "key", "version", and "deleted" properties), we only need to add a corresponding
+  # constant here and the existing store should be able to handle it.
+  #
+  # The :priority and :get_dependency_keys properties are used by FeatureStoreDataSetSorter
+  # to ensure data consistency during non-atomic updates.
+
+  # @private
+  FEATURES = {
+    namespace: "features",
+    priority: 1,  # that is, features should be stored after segments
+    get_dependency_keys: lambda { |flag| (flag[:prerequisites] || []).map { |p| p[:key] } }
+  }.freeze
+
+  # @private
+  SEGMENTS = {
+    namespace: "segments",
+    priority: 0
+  }.freeze
+
+  #
+  # Default implementation of the LaunchDarkly client's feature store, using an in-memory
+  # cache.  This object holds feature flags and related data received from LaunchDarkly.
+  # Database-backed implementations are available in {LaunchDarkly::Integrations}.
+  #
+  class InMemoryFeatureStore
+    include LaunchDarkly::Interfaces::FeatureStore
+
+    def initialize
+      @items = Hash.new
+      @lock = Concurrent::ReadWriteLock.new
+      @initialized = Concurrent::AtomicBoolean.new(false)
+    end
+
+    def get(kind, key)
+      @lock.with_read_lock do
+        coll = @items[kind]
+        f = coll.nil? ? nil : coll[key.to_sym]
+        (f.nil? || f[:deleted]) ? nil : f
+      end
+    end
+
+    def all(kind)
+      @lock.with_read_lock do
+        coll = @items[kind]
+        (coll.nil? ? Hash.new : coll).select { |_k, f| not f[:deleted] }
+      end
+    end
+
+    def delete(kind, key, version)
+      @lock.with_write_lock do
+        coll = @items[kind]
+        if coll.nil?
+          coll = Hash.new
+          @items[kind] = coll
+        end
+        old = coll[key.to_sym]
+
+        if old.nil? || old[:version] < version
+          coll[key.to_sym] = { deleted: true, version: version }
+        end
+      end
+    end
+
+    def init(all_data)
+      @lock.with_write_lock do
+        @items.replace(all_data)
+        @initialized.make_true
+      end
+    end
+
+    def upsert(kind, item)
+      @lock.with_write_lock do
+        coll = @items[kind]
+        if coll.nil?
+          coll = Hash.new
+          @items[kind] = coll
+        end
+        old = coll[item[:key].to_sym]
+
+        if old.nil? || old[:version] < item[:version]
+          coll[item[:key].to_sym] = item
+        end
+      end
+    end
+
+    def initialized?
+      @initialized.value
+    end
+
+    def stop
+      # nothing to do
+    end
+  end
+end

data/lib/ldclient-rb/integrations.rb

@@ -0,0 +1,55 @@
+require "ldclient-rb/integrations/consul"
+require "ldclient-rb/integrations/dynamodb"
+require "ldclient-rb/integrations/redis"
+require "ldclient-rb/integrations/util/store_wrapper"
+
+module LaunchDarkly
+  #
+  # Tools for connecting the LaunchDarkly client to other software.
+  #
+  module Integrations
+    #
+    # Integration with [Consul](https://www.consul.io/).
+    #
+    # Note that in order to use this integration, you must first install the gem `diplomat`.
+    #
+    # @since 5.5.0
+    #
+    module Consul
+      # code is in ldclient-rb/impl/integrations/consul_impl
+    end
+    
+    #
+    # Integration with [DynamoDB](https://aws.amazon.com/dynamodb/).
+    #
+    # Note that in order to use this integration, you must first install one of the AWS SDK gems: either
+    # `aws-sdk-dynamodb`, or the full `aws-sdk`.
+    #
+    # @since 5.5.0
+    #
+    module DynamoDB
+      # code is in ldclient-rb/impl/integrations/dynamodb_impl
+    end
+
+    #
+    # Integration with [Redis](https://redis.io/).
+    #
+    # Note that in order to use this integration, you must first install the `redis` and `connection-pool`
+    # gems.
+    #
+    # @since 5.5.0
+    #
+    module Redis
+      # code is in ldclient-rb/impl/integrations/redis_impl
+    end
+
+    #
+    # Support code that may be helpful in creating integrations.
+    #
+    # @since 5.5.0
+    #
+    module Util
+      # code is in ldclient-rb/integrations/util/
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+require "ldclient-rb/impl/integrations/consul_impl"
+require "ldclient-rb/integrations/util/store_wrapper"
+
+module LaunchDarkly
+  module Integrations
+    module Consul
+      #
+      # Default value for the `prefix` option for {new_feature_store}.
+      #
+      # @return [String]  the default key prefix
+      #
+      def self.default_prefix
+        'launchdarkly'
+      end
+
+      #
+      # Creates a Consul-backed persistent feature store.
+      #
+      # To use this method, you must first install the gem `diplomat`. Then, put the object returned by
+      # this method into the `feature_store` property of your client configuration ({LaunchDarkly::Config}).
+      #
+      # @param opts [Hash] the configuration options
+      # @option opts [Hash] :consul_config  an instance of `Diplomat::Configuration` to replace the default
+      #   Consul client configuration (note that this is exactly the same as modifying `Diplomat.configuration`)
+      # @option opts [String] :url   shortcut for setting the `url` property of the Consul client configuration
+      # @option opts [String] :prefix  namespace prefix to add to all keys used by LaunchDarkly
+      # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
+      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching
+      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
+      # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
+      #
+      def self.new_feature_store(opts, &block)
+        core = LaunchDarkly::Impl::Integrations::Consul::ConsulFeatureStoreCore.new(opts)
+        return LaunchDarkly::Integrations::Util::CachingStoreWrapper.new(core, opts)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+require "ldclient-rb/impl/integrations/dynamodb_impl"
+require "ldclient-rb/integrations/util/store_wrapper"
+
+module LaunchDarkly
+  module Integrations
+    module DynamoDB
+      #
+      # Creates a DynamoDB-backed persistent feature store. For more details about how and why you can
+      # use a persistent feature store, see the
+      # [SDK reference guide](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+      #
+      # To use this method, you must first install one of the AWS SDK gems: either `aws-sdk-dynamodb`, or
+      # the full `aws-sdk`. Then, put the object returned by this method into the `feature_store` property
+      # of your client configuration ({LaunchDarkly::Config}).
+      #
+      # @example Configuring the feature store
+      #     store = LaunchDarkly::Integrations::DynamoDB::new_feature_store("my-table-name")
+      #     config = LaunchDarkly::Config.new(feature_store: store)
+      #     client = LaunchDarkly::LDClient.new(my_sdk_key, config)
+      #
+      # Note that the specified table must already exist in DynamoDB. It must have a partition key called
+      # "namespace", and a sort key called "key" (both strings). The SDK does not create the table
+      # automatically because it has no way of knowing what additional properties (such as permissions
+      # and throughput) you would want it to have.
+      #
+      # By default, the DynamoDB client will try to get your AWS credentials and region name from
+      # environment variables and/or local configuration files, as described in the AWS SDK documentation.
+      # You can also specify any supported AWS SDK options in `dynamodb_opts`-- or, provide an
+      # already-configured DynamoDB client in `existing_client`.
+      #
+      # @param table_name [String] name of an existing DynamoDB table
+      # @param opts [Hash] the configuration options
+      # @option opts [Hash] :dynamodb_opts  options to pass to the DynamoDB client constructor (ignored if you specify `:existing_client`)
+      # @option opts [Object] :existing_client  an already-constructed DynamoDB client for the feature store to use
+      # @option opts [String] :prefix  namespace prefix to add to all keys used by LaunchDarkly
+      # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
+      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching
+      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
+      # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
+      #
+      def self.new_feature_store(table_name, opts)
+        core = LaunchDarkly::Impl::Integrations::DynamoDB::DynamoDBFeatureStoreCore.new(table_name, opts)
+        return LaunchDarkly::Integrations::Util::CachingStoreWrapper.new(core, opts)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+require "ldclient-rb/redis_store"  # eventually we will just refer to impl/integrations/redis_impl directly
+
+module LaunchDarkly
+  module Integrations
+    module Redis
+      #
+      # Default value for the `redis_url` option for {new_feature_store}. This points to an instance of
+      # Redis running at `localhost` with its default port.
+      #
+      # @return [String]  the default Redis URL
+      #
+      def self.default_redis_url
+        'redis://localhost:6379/0'
+      end
+
+      #
+      # Default value for the `prefix` option for {new_feature_store}.
+      #
+      # @return [String]  the default key prefix
+      #
+      def self.default_prefix
+        'launchdarkly'
+      end
+
+      #
+      # Creates a Redis-backed persistent feature store. For more details about how and why you can
+      # use a persistent feature store, see the
+      # [SDK reference guide](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+      #
+      # To use this method, you must first have the `redis` and `connection-pool` gems installed. Then,
+      # put the object returned by this method into the `feature_store` property of your
+      # client configuration.
+      #
+      # @example Configuring the feature store
+      #     store = LaunchDarkly::Integrations::Redis::new_feature_store(redis_url: "redis://my-server")
+      #     config = LaunchDarkly::Config.new(feature_store: store)
+      #     client = LaunchDarkly::LDClient.new(my_sdk_key, config)
+      #
+      # @param opts [Hash] the configuration options
+      # @option opts [String] :redis_url (default_redis_url)  URL of the Redis instance (shortcut for omitting `redis_opts`)
+      # @option opts [Hash] :redis_opts  options to pass to the Redis constructor (if you want to specify more than just `redis_url`)
+      # @option opts [String] :prefix (default_prefix)  namespace prefix to add to all hash keys used by LaunchDarkly
+      # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
+      # @option opts [Integer] :max_connections  size of the Redis connection pool
+      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching
+      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
+      # @option opts [Object] :pool  custom connection pool, if desired
+      # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
+      #
+      def self.new_feature_store(opts)
+        return RedisFeatureStore.new(opts)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,230 @@
+require "concurrent/atomics"
+
+require "ldclient-rb/expiring_cache"
+
+module LaunchDarkly
+  module Integrations
+    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)
+        end
+
+        def init(all_data)
+          @core.init_internal(all_data)
+          @inited.make_true
+
+          if !@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)
+          if !@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]) if !cached.nil?
+          end
+
+          item = @core.get_internal(kind, key)
+
+          if !@cache.nil?
+            @cache[cache_key] = [item]
+          end
+
+          item_if_not_deleted(item)
+        end
+
+        def all(kind)
+          if !@cache.nil?
+            items = @cache[all_cache_key(kind)]
+            return items if !items.nil?
+          end
+
+          items = items_if_not_deleted(@core.get_all_internal(kind))
+          @cache[all_cache_key(kind)] = items if !@cache.nil?
+          items
+        end
+
+        def upsert(kind, item)
+          new_state = @core.upsert_internal(kind, item)
+
+          if !@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