posthog-ruby 3.26.4 → 3.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8ce806f1bb00b10162307764e024a4019e9ea6d924700da5443ad15f430b4c8
-  data.tar.gz: b810a1652c8615a544fc24082b8e99a34ddf3db96c1605e29e8fc36ff2ae3cc3
+  metadata.gz: 125a7a9c4063477324ed9654c1035ff28e959cb6c389dfbcfc5ee08bb17153ab
+  data.tar.gz: b02e50631f58cb0e119184c1556766c55ee0e1ae578514620b6217a916207b7e
 SHA512:
-  metadata.gz: 9b58080118c7780408d1f7e7992ef99d1e4a76db837babc8057e09b826a4ef0b2bd4a5a369cbb164fe8675735cd9074a4d9b312f4532198c2415782a3c8cf820
-  data.tar.gz: 70ea5da7b0cc56c9a96681cc64611e85b931deb63359c64f99507d9bb292b459f1d5c246ba13a8961b28af15e6009fc7338ea6a04f02af74120c05e8e56a65c1
+  metadata.gz: 1adee637ab5766731429e73e4bd41b102c9bb33fc285b75b4a62dd173a6fa0c4825ee47ff87b007d8cc8c517c8eab6103b33337b62fd4504497c2c127580c7c2
+  data.tar.gz: 82c8accf93eede6fe7c4748967377b7fa9a1ffc28f7c9ed85e6355ba81d2312962767488436af285c57e0bfc9ebcd442dd486157644b708e9dbd03ad045fd712

data/lib/posthog/client.rb

@@ -85,9 +85,9 @@ module PostHog
 
     # @param opts [Hash] Client configuration.
     # @option opts [String, nil] :api_key Your project's API key. Missing or blank values disable the client.
-    # @option opts [String, nil] :secret_key The credential used for local feature flag evaluation and remote
-    #   config. Accepts either a Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`). Required
-    #   for local feature flag evaluation.
+    # @option opts [String, nil] :secret_key The credential used to fetch local feature flag definitions and remote
+    #   config. Accepts either a Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`). Not required
+    #   for local evaluation when definitions are read from +:flag_definition_cache_provider+.
     # @option opts [String, nil] :personal_api_key
     #   @deprecated Use +:secret_key+ instead. Retained as an alias; when both are supplied, +:secret_key+ wins.
     # @option opts [String] :host Fully qualified hostname of the PostHog server. Defaults to `https://us.i.posthog.com`.
@@ -180,6 +180,7 @@ module PostHog
       @feature_flags_poller = nil
       @secret_key = secret_key
       @personal_api_key = secret_key
+      @flag_definition_cache_provider = opts[:flag_definition_cache_provider]
 
       if @disabled && !opts[:silence_disabled_client_error]
         logger.error('api_key is missing or empty after trimming whitespace; check your project API key')
@@ -214,7 +215,7 @@ module PostHog
             opts[:host],
             opts[:feature_flag_request_timeout_seconds] || Defaults::FeatureFlags::FLAG_REQUEST_TIMEOUT_SECONDS,
             opts[:on_error],
-            flag_definition_cache_provider: opts[:flag_definition_cache_provider],
+            flag_definition_cache_provider: @flag_definition_cache_provider,
             feature_flag_request_max_retries: opts[:feature_flag_request_max_retries],
             async_load: opts[:feature_flags_async_load] == true,
             user_agent: @headers['User-Agent'],
@@ -883,9 +884,9 @@ module PostHog
     def reload_feature_flags
       return if @disabled
 
-      unless @secret_key
+      unless @secret_key || @flag_definition_cache_provider
         logger.error(
-          'You need to specify a secret_key to locally evaluate feature flags'
+          'You need to specify a secret_key or flag_definition_cache_provider to locally evaluate feature flags'
         )
         return
       end

data/lib/posthog/feature_flag_evaluations.rb

@@ -81,11 +81,20 @@ module PostHog
     end
 
     # @param key [String, Symbol] The feature flag key.
-    # @return [Boolean] true when the flag is enabled, false when disabled or missing.
-    def enabled?(key)
+    # @param default_value [Boolean, nil] Returned when the flag has no value in this
+    #   snapshot — it was never loaded, the `/flags` request failed, or no flag with that
+    #   key exists. A flag that does have a value, including `false` and variant strings,
+    #   always wins over this default; so does a flag the server returned but marked as
+    #   failed, which resolves to `false`. Defaults to `nil`, which keeps the historical
+    #   `false` result for a missing flag.
+    # @return [Boolean] true when the flag is enabled, false when disabled, and the
+    #   caller-supplied default (or false when none was supplied) when the flag is missing.
+    def enabled?(key, default_value: nil)
       key = key.to_s
       flag = @flags[key]
       _record_access(key, flag)
+      return !!default_value if flag.nil? && !default_value.nil?
+
       flag&.enabled ? true : false
     end
 

data/lib/posthog/feature_flags.rb

@@ -100,9 +100,9 @@ module PostHog
           run_now: @async_load
         ) { _load_feature_flags }
 
-      # If no secret_key, disable local evaluation & thus polling for definitions
-      if @secret_key.nil?
-        logger.info 'No secret_key provided, disabling local evaluation'
+      # Local evaluation can load definitions from either the API or an external cache.
+      if @secret_key.nil? && @flag_definition_cache_provider.nil?
+        logger.info 'No secret_key or flag_definition_cache_provider provided, disabling local evaluation'
         @loaded_flags_successfully_once.make_true
       else
         # load once synchronously before timer, unless @async_load
@@ -1260,7 +1260,8 @@ module PostHog
 
       if @flag_definition_cache_provider
         begin
-          should_fetch = @flag_definition_cache_provider.should_fetch_flag_definitions?
+          # Cache-only readers must not acquire or renew fetch leadership.
+          should_fetch = @secret_key && @flag_definition_cache_provider.should_fetch_flag_definitions?
         rescue StandardError => e
           logger.error("[FEATURE FLAGS] Cache provider should_fetch error: #{e}")
           should_fetch = true
@@ -1271,6 +1272,10 @@ module PostHog
         begin
           cached_data = @flag_definition_cache_provider.flag_definitions
           if cached_data
+            unless cached_data.is_a?(Hash) && get_by_symbol_or_string_key(cached_data, 'flags').is_a?(Array)
+              raise ArgumentError, 'Cached flag definitions must contain a flags array'
+            end
+
             logger.debug '[FEATURE FLAGS] Using cached flag definitions from external cache'
             _apply_flag_definitions(cached_data)
             return
@@ -1288,6 +1293,11 @@ module PostHog
     end
 
     def _fetch_and_apply_flag_definitions
+      unless @secret_key
+        logger.warn '[FEATURE FLAGS] A secret_key is required to fetch flag definitions from PostHog'
+        return
+      end
+
       begin
         res = _request_feature_flag_definitions(etag: @flags_etag.value)
       rescue StandardError => e

data/lib/posthog/flag_definition_cache.rb

@@ -5,7 +5,8 @@ module PostHog
   #
   # Enables multi-worker environments (Kubernetes, load-balanced servers,
   # serverless functions) to share flag definitions via an external cache,
-  # reducing redundant API calls.
+  # reducing redundant API calls. Cache consumers need only the project API key;
+  # +:secret_key+ is required only for workers that fetch definitions from PostHog.
   #
   # Implement the four required methods on any object and pass it as the
   # +:flag_definition_cache_provider+ option when creating a {Client}.
@@ -16,7 +17,7 @@ module PostHog
   #   Retrieve cached flag definitions. Return a Hash with +:flags+,
   #   +:group_type_mapping+, +:cohorts+, +:minimal_flag_called_events+, and +:property_matching_version+
   #   keys, or +nil+ if the cache is empty. Returning +nil+ triggers an API
-  #   fetch when no flags are loaded yet (emergency fallback). Providers
+  #   fetch when no flags are loaded yet and +:secret_key+ is configured (emergency fallback). Providers
   #   written before +:minimal_flag_called_events+ existed continue to work;
   #   a missing key is treated as +false+. Preserve +:property_matching_version+
   #   with the definitions: exactly +2+ selects explicit equality; missing/1
@@ -27,7 +28,9 @@ module PostHog
   # @!method should_fetch_flag_definitions?
   #   Return +true+ if this instance should fetch new definitions from the
   #   API, +false+ to read from cache instead. Use for distributed lock
-  #   coordination so only one worker fetches at a time.
+  #   coordination so only one worker fetches at a time. Called only when
+  #   +:secret_key+ is configured. Without it, the SDK reads +flag_definitions+
+  #   directly without acquiring or renewing fetch leadership.
   #   @return [Boolean]
   #
   # @!method on_flag_definitions_received(data)
@@ -53,12 +56,16 @@ module PostHog
   # - +on_flag_definitions_received+ errors are logged; flags remain in memory
   # - +shutdown+ errors are logged; shutdown continues
   #
+  # API fallback requires +:secret_key+. Without it, the SDK logs a warning and
+  # keeps any previously loaded definitions. Cache-only readers skip the fetch
+  # decision and never publish. Polling and manual reloads continue reading the
+  # cache so consumers can pick up later updates.
+  #
   # == Example
   #
   #   cache = RedisFlagCache.new(redis, service_key: 'my-service')
   #   client = PostHog::Client.new(
   #     api_key: '<project_api_key>',
-  #     secret_key: '<secret_key>',
   #     flag_definition_cache_provider: cache
   #   )
   #

data/lib/posthog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PostHog
-  VERSION = '3.26.4'
+  VERSION = '3.27.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.26.4
+  version: 3.27.1
 platform: ruby
 authors:
 - ''