launchdarkly-server-sdk 8.15.0 → 8.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 047cbd8eb2194813d948fae8867456a2ae904370c22e2d9104d40310e9c6c918
-  data.tar.gz: 5617fd2d3f49a081274b05bdc00dc64787b4311117ad85739c6a82a4b32d9a36
+  metadata.gz: b7bea0f24a78b42aa3494b0c36a0523a91671e7db9c3bb264011bc6791c020f7
+  data.tar.gz: fefb72d9bbf9febfb214268935bb289fe3175447bb56529d67a5211ee0b689d5
 SHA512:
-  metadata.gz: 3859a3bce1a0fce43c3c6d13b1e5e134ab2d1c1574ba14f645420e04af098fae64169f7f8f43a54fdb4651fbfc25b1188a4694050f5a7eca1c0db425c7eefe60
-  data.tar.gz: 2e3aa25992a683b6ecdc7b0bb0822c5eb5a41d3e98db03741824dcff0d1820e249bcb4a3504963577a773c4211ae4acc505c253e29ea2b53f7fec17754d8db24
+  metadata.gz: 2c17d728ec723fb03031bea1b6a96f32ce030202ae29ab1dc094cdfad8602489bd69370d95fefd8b4a17fd29b07fac868e04146b3cabb0254b23640ea2256952
+  data.tar.gz: 9fbed6b65e5ec58597e2b09823c9f6ea25ce487a51061910480a123ed8e47eb188adc24e87cf675aed83ae99bfbf2f1d9dfc83ce4c4bb88e4e930bcf23a6a184

data/lib/ldclient-rb/config.rb

@@ -262,6 +262,10 @@ module LaunchDarkly
     # You can also specify the same behavior for an individual flag evaluation
     # by providing the context object with a list of private attributes.
     #
+    # Each entry is an attribute reference. A reference addresses attributes by
+    # symbol name, so it cannot make an attribute private if that attribute was
+    # given a string name. Refer to {LDContext} for the symbol requirement.
+    #
     # @see https://docs.launchdarkly.com/sdk/features/user-context-config#using-private-attributes
     #
     # @return [Array<String>]

data/lib/ldclient-rb/context.rb

@@ -6,6 +6,17 @@ module LaunchDarkly
   # LDContext is a collection of attributes that can be referenced in flag
   # evaluations and analytics events.
   #
+  # Every attribute name must be a symbol. This applies to the built-in
+  # properties, such as :key and :kind, and to custom attributes at every level
+  # of nesting. The SDK addresses attributes by symbol, so it cannot find an
+  # attribute that has a string name. Such an attribute is invisible to flag
+  # evaluation and to private attribute redaction.
+  #
+  # Take care with data that arrives as JSON. `JSON.parse` returns string keys
+  # by default, so pass `symbolize_names: true` before you build a context from
+  # it. Note that the `"name": value` form in a hash literal already produces a
+  # symbol, so a hand-written literal is safe.
+  #
   # To create an LDContext of a single kind, such as a user, you may use
   # {LDContext#create} or {LDContext#with_key}.
   #
@@ -148,6 +159,9 @@ module LaunchDarkly
     #
     # Return an array of top level attribute keys (excluding built-in attributes)
     #
+    # The keys come back in the form the caller supplied. A string key is
+    # returned as a string, even though the SDK cannot address it.
+    #
     # @return [Array<Symbol>]
     #
     def get_custom_attribute_names
@@ -172,6 +186,9 @@ module LaunchDarkly
     # values out of JSON objects or arrays, such as "/address/street". Use
     # {#get_value_for_reference} for that purpose.
     #
+    # The lookup treats the name as a symbol. An attribute that was stored under
+    # a string name is therefore not found, and the result is nil.
+    #
     # If the value is found, the return value is the attribute value;
     # otherwise, it is nil.
     #
@@ -200,6 +217,10 @@ module LaunchDarkly
     # Use {#individual_context} to inspect a Context for a particular kind and
     # then get its attributes.
     #
+    # A Reference holds its path components as symbols, so each step of the
+    # lookup matches a symbol key. A path that crosses an attribute with a
+    # string name resolves to nil.
+    #
     # If the value is found, the return value is the attribute value;
     # otherwise, it is nil.
     #
@@ -440,6 +461,14 @@ module LaunchDarkly
     # {https://docs.launchdarkly.com/sdk/features/user-config SDK
     # documentation}.
     #
+    # Every key in the hash must be a symbol, at the top level and inside any
+    # nested attribute value. Refer to the {LDContext} class documentation for
+    # why, and for the JSON.parse caveat.
+    #
+    # A string key does not make the context invalid, with two exceptions. The
+    # context requires a symbol :kind and a symbol :key, so a hash that supplies
+    # those as strings is invalid.
+    #
     # @param data [Hash]
     # @return [LDContext]
     #

data/lib/ldclient-rb/events.rb

@@ -487,7 +487,7 @@ module LaunchDarkly
     SUMMARY_KIND = 'summary'
 
     def initialize(config)
-      @context_filter = LaunchDarkly::Impl::ContextFilter.new(config.all_attributes_private, config.private_attributes)
+      @context_filter = LaunchDarkly::Impl::ContextFilter.new(config.all_attributes_private, config.private_attributes, config.logger)
     end
 
     # Transforms events into the format used for event sending.

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

@@ -1,12 +1,17 @@
+require "concurrent/atomics"
+
 module LaunchDarkly
   module Impl
     class ContextFilter
       #
       # @param all_attributes_private [Boolean]
       # @param private_attributes [Array<String>]
+      # @param logger [Logger, nil]
       #
-      def initialize(all_attributes_private, private_attributes)
+      def initialize(all_attributes_private, private_attributes, logger = nil)
         @all_attributes_private = all_attributes_private
+        @logger = logger
+        @non_symbol_name_logged = Concurrent::AtomicBoolean.new(false)
 
         @private_attributes = []
         private_attributes.each do |attribute|
@@ -78,9 +83,14 @@ module LaunchDarkly
         end
 
         context.get_custom_attribute_names.each do |attribute|
+          unless attribute.is_a?(Symbol)
+            log_non_symbol_name(attribute)
+            next
+          end
+
           unless check_whole_attribute_private(Reference.create_literal(attribute), private_attributes, redacted, anonymous && redact_anonymous)
             value = context.get_value(attribute)
-            filtered[attribute] = redact_json_value(nil, attribute, value, private_attributes, redacted)
+            filtered[attribute] = redact_json_value(nil, attribute, value, private_attributes, redacted, [])
           end
         end
 
@@ -122,16 +132,34 @@ module LaunchDarkly
       # @param value [any]
       # @param private_attributes [Array<Reference>]
       # @param redacted [Array<Symbol>]
+      # @param visited [Array<Hash>]
       # @return [any]
       #
-      private def redact_json_value(parent_path, name, value, private_attributes, redacted)
+      private def redact_json_value(parent_path, name, value, private_attributes, redacted, visited)
         return value unless value.is_a?(Hash)
 
         ret = {}
         current_path = parent_path.clone || []
         current_path << name
 
+        # The chain of hashes from the attribute root down to this value. A
+        # nested value that points back into this chain is a cycle and is
+        # omitted.
+        #
+        # The comparison is by object identity, which keeps the check cheap.
+        # Context creation copies each top-level attribute value, so a cycle
+        # through that value appears once in the output before it is cut.
+        # Private attribute references match the paths that appear in the
+        # output. Cyclic values are not valid context data; this check only
+        # prevents unbounded recursion.
+        branch = visited + [value]
+
         value.each do |k, v|
+          unless k.is_a?(Symbol)
+            log_non_symbol_name(k)
+            next
+          end
+
           was_redacted = false
           private_attributes.each do |private_attribute|
             next unless private_attribute.depth == (current_path.count + 1)
@@ -155,12 +183,34 @@ module LaunchDarkly
           end
 
           unless was_redacted
-            ret[k] = redact_json_value(current_path, k, v, private_attributes, redacted)
+            next if v.is_a?(Hash) && branch.any? { |seen| seen.equal?(v) }
+
+            ret[k] = redact_json_value(current_path, k, v, private_attributes, redacted, branch)
           end
         end
 
         ret
       end
+
+      #
+      # Log the first attribute found with a non-symbol name. Later
+      # occurrences are not logged to prevent log spam.
+      #
+      # Attribute references cannot address non-symbol names, so these
+      # attributes cannot be evaluated or redacted. They are omitted from
+      # analytics events.
+      #
+      # @param name [any]
+      #
+      private def log_non_symbol_name(name)
+        return if @logger.nil?
+        return unless @non_symbol_name_logged.make_true
+
+        @logger.error do
+          "[LDClient] Context attributes with non-symbol names cannot be evaluated or redacted, " \
+            "so they are omitted from analytics events (first occurrence: #{name.inspect}). This message is logged once."
+        end
+      end
     end
   end
 end

data/lib/ldclient-rb/impl/data_source/polling.rb

@@ -67,8 +67,11 @@ module LaunchDarkly
                 error_info
               )
             else
-              @ready.set  # if client was waiting on us, make it stop waiting - has no effect if already set
+              # Publish the OFF status before releasing anyone waiting on the
+              # ready event, so a client that returns from start can rely on the
+              # data source status already reflecting the failure.
               stop_with_error_info error_info
+              @ready.set  # if client was waiting on us, make it stop waiting - has no effect if already set
             end
           rescue StandardError => e
             Impl::Util.log_exception(@config.logger, "Exception while polling", e)

data/lib/ldclient-rb/ldclient.rb

@@ -33,10 +33,6 @@ module LaunchDarkly
 
     def_delegators :@config, :logger
 
-    # @!method flush
-    #   Delegates to {LaunchDarkly::EventProcessorMethods#flush}.
-    def_delegator :@event_processor, :flush
-
     # @!method data_store_status_provider
     #   Delegates to the data system {LaunchDarkly::Impl::DataSystem#data_store_status_provider}.
     #   @return [LaunchDarkly::Interfaces::DataStore::StatusProvider]
@@ -79,6 +75,12 @@ module LaunchDarkly
       config.instance_id = SecureRandom.uuid
       @config = config
 
+      # The pid of the process that owns this client's background threads. A child process that
+      # inherits this client after a fork has a different pid. See #check_forked.
+      @owner_pid = Process.pid
+      # The pid of the process in which the fork warning was last logged, or nil.
+      @fork_warned_pid = Concurrent::AtomicReference.new(nil)
+
       start_up(wait_for_sec)
     end
 
@@ -97,6 +99,10 @@ module LaunchDarkly
     # reason, it is recommended that any listener or hook integrations be added postfork unless you are certain it can
     # survive the forking process.
     #
+    # If the SDK is used in a forked child process before this method is called, it logs a warning once per process.
+    # The warning says that flag updates and analytics events will not work until `postfork` is called. Calling this
+    # method clears that condition for the current process.
+    #
     # @param wait_for_sec [Float] maximum time (in seconds) to wait for initialization
     #
     def postfork(wait_for_sec = 5)
@@ -105,9 +111,51 @@ module LaunchDarkly
       @big_segment_store_manager = nil
       @flag_tracker = nil
 
+      @owner_pid = Process.pid
+      @fork_warned_pid.set(nil)
+
       start_up(wait_for_sec)
     end
 
+    FORK_WARNING_MESSAGE = "[LDClient] This process was forked after the LDClient was created. Background threads do not " +
+      "survive a fork, so flag updates and analytics events will not work in this process. Call LDClient#postfork after forking."
+    private_constant :FORK_WARNING_MESSAGE
+
+    #
+    # Log a warning once per process if this client is used in a process that was forked after the client was created.
+    #
+    # Ruby threads do not survive a fork. A child process that inherits a client has no stream thread, no event
+    # dispatcher thread, and no timer tasks, so flag updates and analytics events stop working. The SDK does not
+    # repair this by itself; the application must call {#postfork}.
+    #
+    # The check compares the current pid with the pid recorded in the constructor or in {#postfork}. It is a single
+    # `getpid` call, which is cheap compared to a flag evaluation. The "already warned" state is stored as the pid in
+    # which the warning was logged, not as a boolean. A boolean would be copied into every child on fork, so a
+    # grandchild process would inherit "already warned" from its parent and never get its own warning.
+    #
+    private def check_forked
+      pid = Process.pid
+      return if pid == @owner_pid
+      return unless fork_breaks_client?
+
+      if @fork_warned_pid.get_and_set(pid) != pid
+        @config.logger.warn { FORK_WARNING_MESSAGE }
+      end
+    end
+
+    #
+    # Return true if this configuration needs background threads. Offline mode has none. LDD mode with events
+    # disabled reads flags from the persistent store and sends nothing, so a fork does not break it.
+    #
+    # @return [Boolean]
+    #
+    private def fork_breaks_client?
+      return false if @config.offline?
+      return false if @config.use_ldd? && !@config.send_events
+
+      true
+    end
+
     private def start_up(wait_for_sec)
       environment_metadata = get_environment_metadata
       plugin_hooks = get_plugin_hooks(environment_metadata)
@@ -281,6 +329,7 @@ module LaunchDarkly
     # @return the variation for the provided context, or the default value if there's an error
     #
     def variation(key, context, default)
+      check_forked
       context = Impl::Context::make_context(context)
       result = evaluate_with_hooks(key, context, default, :variation) do
         detail, _, _ = variation_with_flag(key, context, default)
@@ -314,6 +363,7 @@ module LaunchDarkly
     # @return [EvaluationDetail] an object describing the result
     #
     def variation_detail(key, context, default)
+      check_forked
       context = Impl::Context::make_context(context)
       result = evaluate_with_hooks(key, context, default, :variation_detail) do
         detail, _, _ = evaluate_internal(key, context, default, true)
@@ -439,6 +489,7 @@ module LaunchDarkly
     # @return [Array<Symbol, Interfaces::Migrations::OpTracker>]
     #
     def migration_variation(key, context, default_stage)
+      check_forked
       unless Migrations::VALID_STAGES.include? default_stage
         @config.logger.error { "[LDClient] default_stage #{default_stage} is not a valid stage; continuing with 'off' as default" }
         default_stage = Migrations::STAGE_OFF
@@ -480,6 +531,7 @@ module LaunchDarkly
     # @return [void]
     #
     def identify(context)
+      check_forked
       context = LaunchDarkly::Impl::Context.make_context(context)
       unless context.valid?
         @config.logger.warn("Identify called with invalid context: #{context.error}")
@@ -516,6 +568,7 @@ module LaunchDarkly
     # @return [void]
     #
     def track(event_name, context, data = nil, metric_value = nil)
+      check_forked
       context = LaunchDarkly::Impl::Context.make_context(context)
       unless context.valid?
         @config.logger.warn("Track called with invalid context: #{context.error}")
@@ -536,6 +589,7 @@ module LaunchDarkly
     # @param tracker [LaunchDarkly::Interfaces::Migrations::OpTracker]
     #
     def track_migration_op(tracker)
+      check_forked
       unless tracker.is_a? LaunchDarkly::Interfaces::Migrations::OpTracker
         @config.logger.error { "invalid op tracker received in track_migration_op" }
         return
@@ -571,6 +625,8 @@ module LaunchDarkly
     def all_flags_state(context, options={})
       return FeatureFlagsState.new(false) if @config.offline?
 
+      check_forked
+
       unless initialized?
         if @data_system.store.initialized?
             @config.logger.warn { "Called all_flags_state before client initialization; using last known values from data store" }
@@ -628,11 +684,24 @@ module LaunchDarkly
       state
     end
 
+    #
+    # Tells the client that all pending analytics events should be delivered as soon as possible.
+    #
+    # Delegates to {LaunchDarkly::EventProcessorMethods#flush}.
+    #
+    # @return [void]
+    #
+    def flush
+      check_forked
+      @event_processor.flush
+    end
+
     #
     # Releases all network connections and other resources held by the client, making it no longer usable.
     #
     # @return [void]
     def close
+      check_forked
       @config.logger.info { "[LDClient] Closing LaunchDarkly client..." }
       @data_system.stop
       @event_processor.stop

data/lib/ldclient-rb/reference.rb

@@ -12,6 +12,10 @@ module LaunchDarkly
   # or to identify an attribute or nested value that should be considered
   # private.
   #
+  # A Reference holds its path components as symbols, whichever form the input
+  # string used. It therefore addresses only context attributes that have symbol
+  # names, which is the form a context requires.
+  #
   # Parsing and validation are done at the time that the Reference is
   # constructed. If a Reference instance was created from an invalid string, it
   # is considered invalid and its {Reference#error} attribute will return a

data/lib/ldclient-rb/version.rb

@@ -1,3 +1,3 @@
 module LaunchDarkly
-  VERSION = "8.15.0" # x-release-please-version
+  VERSION = "8.16.0" # x-release-please-version
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: launchdarkly-server-sdk
 version: !ruby/object:Gem::Version
-  version: 8.15.0
+  version: 8.16.0
 platform: ruby
 authors:
 - LaunchDarkly
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb