launchdarkly-server-sdk 6.2.2 → 6.3.0

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
   #
@@ -9,7 +10,7 @@ module LaunchDarkly
     # client uses the feature store to persist feature flags and related objects received from
     # the LaunchDarkly service. Implementations must support concurrent access and updates.
     # For more about how feature stores can be used, see:
-    # [Using a persistent feature store](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+    # [Using a persistent feature store](https://docs.launchdarkly.com/sdk/features/storing-data#ruby).
     #
     # An entity that can be stored in a feature store is a hash that can be converted to and from
     # JSON, and that has at a minimum the following properties: `:key`, a string that is unique
@@ -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 user.
+      #
+      # The user_hash is a base64-encoded string produced by hashing the user 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 user 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 user is explicitly included in
+      # the segment, false if the user 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 user'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 user_hash [String]
+      # @return [Hash] true/false values for Big Segments that reference this user
+      #
+      def get_membership(user_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 user 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 user 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 users 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 user 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 user 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

data/lib/ldclient-rb/ldclient.rb

@@ -1,3 +1,4 @@
+require "ldclient-rb/impl/big_segments"
 require "ldclient-rb/impl/diagnostic_events"
 require "ldclient-rb/impl/evaluator"
 require "ldclient-rb/impl/event_factory"
@@ -57,10 +58,14 @@ module LaunchDarkly
       updated_config.instance_variable_set(:@feature_store, @store)
       @config = updated_config
 
+      @big_segment_store_manager = Impl::BigSegmentStoreManager.new(config.big_segments, @config.logger)
+      @big_segment_store_status_provider = @big_segment_store_manager.status_provider
+
       get_flag = lambda { |key| @store.get(FEATURES, key) }
       get_segment = lambda { |key| @store.get(SEGMENTS, key) }
-      @evaluator = LaunchDarkly::Impl::Evaluator.new(get_flag, get_segment, @config.logger)
-
+      get_big_segments_membership = lambda { |key| @big_segment_store_manager.get_user_membership(key) }
+      @evaluator = LaunchDarkly::Impl::Evaluator.new(get_flag, get_segment, get_big_segments_membership, @config.logger)
+      
       if !@config.offline? && @config.send_events && !@config.diagnostic_opt_out?
         diagnostic_accumulator = Impl::DiagnosticAccumulator.new(Impl::DiagnosticAccumulator.create_diagnostic_id(sdk_key))
       else
@@ -132,7 +137,7 @@ module LaunchDarkly
 
     #
     # Creates a hash string that can be used by the JavaScript SDK to identify a user.
-    # For more information, see [Secure mode](https://docs.launchdarkly.com/docs/js-sdk-reference#section-secure-mode).
+    # For more information, see [Secure mode](https://docs.launchdarkly.com/sdk/features/secure-mode#ruby).
     #
     # @param user [Hash] the user properties
     # @return [String] a hash string
@@ -172,11 +177,11 @@ module LaunchDarkly
     #
     # Other supported user attributes include IP address, country code, and an arbitrary hash of
     # custom attributes. For more about the supported user properties and how they work in
-    # LaunchDarkly, see [Targeting users](https://docs.launchdarkly.com/docs/targeting-users).
+    # LaunchDarkly, see [Targeting users](https://docs.launchdarkly.com/home/flags/targeting-users).
     # 
     # The optional `:privateAttributeNames` user property allows you to specify a list of
     # attribute names that should not be sent back to LaunchDarkly.
-    # [Private attributes](https://docs.launchdarkly.com/docs/private-user-attributes)
+    # [Private attributes](https://docs.launchdarkly.com/home/users/attributes#creating-private-user-attributes)
     # can also be configured globally in {Config}.
     #
     # @example Basic user hash
@@ -213,7 +218,7 @@ module LaunchDarkly
     # be included in analytics events, if you are capturing detailed event data for this flag.
     #
     # For more information, see the reference guide on
-    # [Evaluation reasons](https://docs.launchdarkly.com/v2.0/docs/evaluation-reasons).
+    # [Evaluation reasons](https://docs.launchdarkly.com/sdk/concepts/evaluation-reasons).
     #
     # @param key [String] the unique feature key for the feature flag, as shown
     #   on the LaunchDarkly dashboard
@@ -260,7 +265,7 @@ module LaunchDarkly
     #
     # As of this version’s release date, the LaunchDarkly service does not support the `metricValue`
     # parameter. As a result, specifying `metricValue` will not yet produce any different behavior
-    # from omitting it. Refer to the [SDK reference guide](https://docs.launchdarkly.com/docs/ruby-sdk-reference#section-track)
+    # from omitting it. Refer to the [SDK reference guide](https://docs.launchdarkly.com/sdk/features/events#ruby)
     # for the latest status.
     #
     # @param event_name [String] The name of the event
@@ -375,9 +380,18 @@ module LaunchDarkly
       @config.logger.info { "[LDClient] Closing LaunchDarkly client..." }
       @data_source.stop
       @event_processor.stop
+      @big_segment_store_manager.stop
       @store.stop
     end
 
+    #
+    # Returns an interface for tracking the status of a Big Segment store.
+    #
+    # The {BigSegmentStoreStatusProvider} has methods for checking whether the Big Segment store
+    # is (as far as the SDK knows) currently operational and tracking changes in this status.
+    #
+    attr_reader :big_segment_store_status_provider
+
     private
 
     def create_default_data_source(sdk_key, config, diagnostic_accumulator)

data/lib/ldclient-rb/polling.rb

@@ -1,3 +1,5 @@
+require "ldclient-rb/impl/repeating_task"
+
 require "concurrent/atomics"
 require "thread"
 
@@ -9,8 +11,8 @@ module LaunchDarkly
       @requestor = requestor
       @initialized = Concurrent::AtomicBoolean.new(false)
       @started = Concurrent::AtomicBoolean.new(false)
-      @stopped = Concurrent::AtomicBoolean.new(false)
       @ready = Concurrent::Event.new
+      @task = Impl::RepeatingTask.new(@config.poll_interval, 0, -> { self.poll }, @config.logger)
     end
 
     def initialized?
@@ -20,56 +22,35 @@ module LaunchDarkly
     def start
       return @ready unless @started.make_true
       @config.logger.info { "[LDClient] Initializing polling connection" }
-      create_worker
+      @task.start
       @ready
     end
 
     def stop
-      if @stopped.make_true
-        if @worker && @worker.alive? && @worker != Thread.current
-          @worker.run  # causes the thread to wake up if it's currently in a sleep
-          @worker.join
-        end
-        @config.logger.info { "[LDClient] Polling connection stopped" }
-      end
+      @task.stop
+      @config.logger.info { "[LDClient] Polling connection stopped" }
     end
 
     def poll
-      all_data = @requestor.request_all_data
-      if all_data
-        @config.feature_store.init(all_data)
-        if @initialized.make_true
-          @config.logger.info { "[LDClient] Polling connection initialized" }
-          @ready.set
-        end
-      end
-    end
-
-    def create_worker
-      @worker = Thread.new do
-        @config.logger.debug { "[LDClient] Starting polling worker" }
-        while !@stopped.value do
-          started_at = Time.now
-          begin
-            poll
-          rescue UnexpectedResponseError => e
-            message = Util.http_error_message(e.status, "polling request", "will retry")
-            @config.logger.error { "[LDClient] #{message}" };
-            if !Util.http_error_recoverable?(e.status)
-              @ready.set  # if client was waiting on us, make it stop waiting - has no effect if already set
-              stop
-            end
-          rescue StandardError => exn
-            Util.log_exception(@config.logger, "Exception while polling", exn)
-          end
-          delta = @config.poll_interval - (Time.now - started_at)
-          if delta > 0
-            sleep(delta)
+      begin
+        all_data = @requestor.request_all_data
+        if all_data
+          @config.feature_store.init(all_data)
+          if @initialized.make_true
+            @config.logger.info { "[LDClient] Polling connection initialized" }
+            @ready.set
           end
         end
+      rescue UnexpectedResponseError => e
+        message = Util.http_error_message(e.status, "polling request", "will retry")
+        @config.logger.error { "[LDClient] #{message}" };
+        if !Util.http_error_recoverable?(e.status)
+          @ready.set  # if client was waiting on us, make it stop waiting - has no effect if already set
+          stop
+        end
+      rescue StandardError => e
+        Util.log_exception(@config.logger, "Exception while polling", e)
       end
     end
-
-    private :poll, :create_worker
   end
 end

data/lib/ldclient-rb/util.rb

@@ -18,7 +18,7 @@ module LaunchDarkly
       end
       ret
     end
-    
+
     def self.new_http_client(uri_s, config)
       http_client_options = {}
       if config.socket_factory

data/lib/ldclient-rb/version.rb

@@ -1,3 +1,3 @@
 module LaunchDarkly
-  VERSION = "6.2.2"
+  VERSION = "6.3.0"
 end