ldclient-rb 5.4.3 → 5.5.0

data/lib/ldclient-rb/in_memory_store.rb

@@ -6,20 +6,31 @@ module LaunchDarkly
   # 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"
+    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"
+    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 the
-  # streaming API.
+  # 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

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_seconds (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_seconds (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_seconds (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_seconds (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