launchdarkly-server-sdk 6.2.5 → 7.0.0

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? then
+          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] then
+            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? then
+            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

@@ -4,6 +4,11 @@ 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}
@@ -17,7 +22,7 @@ module LaunchDarkly
       #
       class CachingStoreWrapper
         include LaunchDarkly::Interfaces::FeatureStore
-        
+
         #
         # Creates a new store wrapper instance.
         #
@@ -44,7 +49,7 @@ module LaunchDarkly
           @core.init_internal(all_data)
           @inited.make_true
 
-          if !@cache.nil?
+          unless @cache.nil?
             @cache.clear
             all_data.each do |kind, items|
               @cache[kind] = items_if_not_deleted(items)
@@ -56,15 +61,15 @@ module LaunchDarkly
         end
 
         def get(kind, key)
-          if !@cache.nil?
+          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]) if !cached.nil?
+            return item_if_not_deleted(cached[0]) unless cached.nil?
           end
 
           item = @core.get_internal(kind, key)
 
-          if !@cache.nil?
+          unless @cache.nil?
             @cache[cache_key] = [item]
           end
 
@@ -72,20 +77,20 @@ module LaunchDarkly
         end
 
         def all(kind)
-          if !@cache.nil?
+          unless @cache.nil?
             items = @cache[all_cache_key(kind)]
-            return items if !items.nil?
+            return items unless items.nil?
           end
 
           items = items_if_not_deleted(@core.get_all_internal(kind))
-          @cache[all_cache_key(kind)] = items if !@cache.nil?
+          @cache[all_cache_key(kind)] = items unless @cache.nil?
           items
         end
 
         def upsert(kind, item)
           new_state = @core.upsert_internal(kind, item)
 
-          if !@cache.nil?
+          unless @cache.nil?
             @cache[item_cache_key(kind, item[:key])] = [new_state]
             @cache.delete(all_cache_key(kind))
           end

data/lib/ldclient-rb/integrations.rb

@@ -1,55 +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"
-
-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/interfaces.rb

@@ -1,3 +1,4 @@
+require "observer"
 
 module LaunchDarkly
   #
@@ -120,7 +121,8 @@ module LaunchDarkly
     #
     # The client has its own standard implementation, which uses either a streaming connection or
     # polling depending on your configuration. Normally you will not need to use another one
-    # except for testing purposes. {FileDataSource} provides one such test fixture.
+    # except for testing purposes. Two such test fixtures are {LaunchDarkly::Integrations::FileData}
+    # and {LaunchDarkly::Integrations::TestData}.
     #
     module DataSource
       #
@@ -149,5 +151,153 @@ module LaunchDarkly
       def stop
       end
     end
+
+    module BigSegmentStore
+      #
+      # Returns information about the overall state of the store. This method will be called only
+      # when the SDK needs the latest state, so it should not be cached.
+      #
+      # @return [BigSegmentStoreMetadata]
+      #
+      def get_metadata
+      end
+
+      #
+      # Queries the store for a snapshot of the current segment state for a specific context.
+      #
+      # The context_hash is a base64-encoded string produced by hashing the context key as defined by
+      # the Big Segments specification; the store implementation does not need to know the details
+      # of how this is done, because it deals only with already-hashed keys, but the string can be
+      # assumed to only contain characters that are valid in base64.
+      #
+      # The return value should be either a Hash, or nil if the context is not referenced in any big
+      # segments. Each key in the Hash is a "segment reference", which is how segments are
+      # identified in Big Segment data. This string is not identical to the segment key-- the SDK
+      # will add other information. The store implementation should not be concerned with the
+      # format of the string. Each value in the Hash is true if the context is explicitly included in
+      # the segment, false if the context is explicitly excluded from the segment-- and is not also
+      # explicitly included (that is, if both an include and an exclude existed in the data, the
+      # include would take precedence). If the context's status in a particular segment is undefined,
+      # there should be no key or value for that segment.
+      #
+      # This Hash may be cached by the SDK, so it should not be modified after it is created. It
+      # is a snapshot of the segment membership state at one point in time.
+      #
+      # @param context_hash [String]
+      # @return [Hash] true/false values for Big Segments that reference this context
+      #
+      def get_membership(context_hash)
+      end
+
+      #
+      # Performs any necessary cleanup to shut down the store when the client is being shut down.
+      #
+      # @return [void]
+      #
+      def stop
+      end
+    end
+
+    #
+    # Values returned by {BigSegmentStore#get_metadata}.
+    #
+    class BigSegmentStoreMetadata
+      def initialize(last_up_to_date)
+        @last_up_to_date = last_up_to_date
+      end
+
+      # The Unix epoch millisecond timestamp of the last update to the {BigSegmentStore}. It is
+      # nil if the store has never been updated.
+      #
+      # @return [Integer|nil]
+      attr_reader :last_up_to_date
+    end
+
+    #
+    # Information about the status of a Big Segment store, provided by {BigSegmentStoreStatusProvider}.
+    #
+    # Big Segments are a specific type of segments. For more information, read the LaunchDarkly
+    # documentation: https://docs.launchdarkly.com/home/users/big-segments
+    #
+    class BigSegmentStoreStatus
+      def initialize(available, stale)
+        @available = available
+        @stale = stale
+      end
+
+      # True if the Big Segment store is able to respond to queries, so that the SDK can evaluate
+      # whether a context is in a segment or not.
+      #
+      # If this property is false, the store is not able to make queries (for instance, it may not have
+      # a valid database connection). In this case, the SDK will treat any reference to a Big Segment
+      # as if no contexts are included in that segment. Also, the {EvaluationReason} associated with
+      # with any flag evaluation that references a Big Segment when the store is not available will
+      # have a `big_segments_status` of `STORE_ERROR`.
+      #
+      # @return [Boolean]
+      attr_reader :available
+
+      # True if the Big Segment store is available, but has not been updated within the amount of time
+      # specified by {BigSegmentsConfig#stale_after}.
+      #
+      # This may indicate that the LaunchDarkly Relay Proxy, which populates the store, has stopped
+      # running or has become unable to receive fresh data from LaunchDarkly. Any feature flag
+      # evaluations that reference a Big Segment will be using the last known data, which may be out
+      # of date. Also, the {EvaluationReason} associated with those evaluations will have a
+      # `big_segments_status` of `STALE`.
+      #
+      # @return [Boolean]
+      attr_reader :stale
+
+      def ==(other)
+        self.available == other.available && self.stale == other.stale
+      end
+    end
+
+    #
+    # An interface for querying the status of a Big Segment store.
+    #
+    # The Big Segment store is the component that receives information about Big Segments, normally
+    # from a database populated by the LaunchDarkly Relay Proxy. Big Segments are a specific type
+    # of segments. For more information, read the LaunchDarkly documentation:
+    # https://docs.launchdarkly.com/home/users/big-segments
+    #
+    # An implementation of this interface is returned by {LDClient#big_segment_store_status_provider}.
+    # Application code never needs to implement this interface.
+    #
+    # There are two ways to interact with the status. One is to simply get the current status; if its
+    # `available` property is true, then the SDK is able to evaluate context membership in Big Segments,
+    # and the `stale`` property indicates whether the data might be out of date.
+    #
+    # The other way is to subscribe to status change notifications. Applications may wish to know if
+    # there is an outage in the Big Segment store, or if it has become stale (the Relay Proxy has
+    # stopped updating it with new data), since then flag evaluations that reference a Big Segment
+    # might return incorrect values. To allow finding out about status changes as soon as possible,
+    # `BigSegmentStoreStatusProvider` mixes in Ruby's
+    # [Observable](https://docs.ruby-lang.org/en/2.5.0/Observable.html) module to provide standard
+    # methods such as `add_observer`. Observers will be called with a new {BigSegmentStoreStatus}
+    # value whenever the status changes.
+    #
+    # @example Getting the current status
+    #   status = client.big_segment_store_status_provider.status
+    #
+    # @example Subscribing to status notifications
+    #   client.big_segment_store_status_provider.add_observer(self, :big_segments_status_changed)
+    #
+    #   def big_segments_status_changed(new_status)
+    #     puts "Big segment store status is now: #{new_status}"
+    #   end
+    #
+    module BigSegmentStoreStatusProvider
+      include Observable
+      #
+      # Gets the current status of the store, if known.
+      #
+      # @return [BigSegmentStoreStatus] the status, or nil if the SDK has not yet queried the Big
+      #   Segment store status
+      #
+      def status
+      end
+    end
   end
 end