Module: PostHog::FlagDefinitionCacheProvider

Defined in:
lib/posthog/flag_definition_cache.rb

Overview

Interface for external caching of feature flag definitions.

EXPERIMENTAL: This API may change in future minor version bumps.

Enables multi-worker environments (Kubernetes, load-balanced servers, serverless functions) to share flag definitions via an external cache, reducing redundant API calls.

Implement the four required methods on any object and pass it as the :flag_definition_cache_provider option when creating a Client.

Required Methods

Error Handling

All methods are wrapped in begin/rescue. Errors are logged but never break flag evaluation:

  • should_fetch_flag_definitions? errors default to fetching (fail-safe)

  • flag_definitions errors fall back to API fetch

  • on_flag_definitions_received errors are logged; flags remain in memory

  • shutdown errors are logged; shutdown continues

Example

cache = RedisFlagCache.new(redis, service_key: 'my-service')
client = PostHog::Client.new(
  api_key: '<project_api_key>',
  personal_api_key: '<personal_api_key>',
  flag_definition_cache_provider: cache
)

Constant Summary collapse

REQUIRED_METHODS = 
%i[
  flag_definitions
  should_fetch_flag_definitions?
  on_flag_definitions_received
  shutdown
].freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.validate!(provider) ⇒ void

This method returns an undefined value.

Validates that provider implements all required methods. Raises ArgumentError listing any missing methods.

Parameters:

  • provider (Object) —

    the cache provider to validate

Raises:

  • (ArgumentError) —

    if any required methods are missing



75
76
77
78
79
80
81
82
 
# File 'lib/posthog/flag_definition_cache.rb', line 75

def self.validate!(provider)
  missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
  return if missing.empty?

  raise ArgumentError,
        "Flag definition cache provider is missing required methods: #{missing.join(', ')}. " \
        'See PostHog::FlagDefinitionCacheProvider for the required interface.'
end

Instance Method Details

#flag_definitions ⇒ Hash?

Retrieve cached flag definitions. Return a Hash with :flags, :group_type_mapping, and :cohorts keys, or nil if the cache is empty. Returning nil triggers an API fetch when no flags are loaded yet (emergency fallback).

Returns:

  • (Hash, nil) 


61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/posthog/flag_definition_cache.rb', line 61

module FlagDefinitionCacheProvider
  REQUIRED_METHODS = %i[
    flag_definitions
    should_fetch_flag_definitions?
    on_flag_definitions_received
    shutdown
  ].freeze

  # Validates that +provider+ implements all required methods.
  # Raises +ArgumentError+ listing any missing methods.
  #
  # @param provider [Object] the cache provider to validate
  # @raise [ArgumentError] if any required methods are missing
  # @return [void]
  def self.validate!(provider)
    missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
    return if missing.empty?

    raise ArgumentError,
          "Flag definition cache provider is missing required methods: #{missing.join(', ')}. " \
          'See PostHog::FlagDefinitionCacheProvider for the required interface.'
  end
end

#on_flag_definitions_received(data) ⇒ void

This method returns an undefined value.

Called after successfully fetching new definitions from the API. data is a Hash with :flags, :group_type_mapping, and :cohorts

keys (plain Ruby types, not Concurrent

wrappers). Store it in your

external cache.

Parameters:

  • data (Hash) 


61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/posthog/flag_definition_cache.rb', line 61

module FlagDefinitionCacheProvider
  REQUIRED_METHODS = %i[
    flag_definitions
    should_fetch_flag_definitions?
    on_flag_definitions_received
    shutdown
  ].freeze

  # Validates that +provider+ implements all required methods.
  # Raises +ArgumentError+ listing any missing methods.
  #
  # @param provider [Object] the cache provider to validate
  # @raise [ArgumentError] if any required methods are missing
  # @return [void]
  def self.validate!(provider)
    missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
    return if missing.empty?

    raise ArgumentError,
          "Flag definition cache provider is missing required methods: #{missing.join(', ')}. " \
          'See PostHog::FlagDefinitionCacheProvider for the required interface.'
  end
end

#should_fetch_flag_definitions? ⇒ Boolean

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.

Returns:

  • (Boolean) 


61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/posthog/flag_definition_cache.rb', line 61

module FlagDefinitionCacheProvider
  REQUIRED_METHODS = %i[
    flag_definitions
    should_fetch_flag_definitions?
    on_flag_definitions_received
    shutdown
  ].freeze

  # Validates that +provider+ implements all required methods.
  # Raises +ArgumentError+ listing any missing methods.
  #
  # @param provider [Object] the cache provider to validate
  # @raise [ArgumentError] if any required methods are missing
  # @return [void]
  def self.validate!(provider)
    missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
    return if missing.empty?

    raise ArgumentError,
          "Flag definition cache provider is missing required methods: #{missing.join(', ')}. " \
          'See PostHog::FlagDefinitionCacheProvider for the required interface.'
  end
end

#shutdown ⇒ void

This method returns an undefined value.

Called when the PostHog client shuts down. Release any distributed locks and clean up resources.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/posthog/flag_definition_cache.rb', line 61

module FlagDefinitionCacheProvider
  REQUIRED_METHODS = %i[
    flag_definitions
    should_fetch_flag_definitions?
    on_flag_definitions_received
    shutdown
  ].freeze

  # Validates that +provider+ implements all required methods.
  # Raises +ArgumentError+ listing any missing methods.
  #
  # @param provider [Object] the cache provider to validate
  # @raise [ArgumentError] if any required methods are missing
  # @return [void]
  def self.validate!(provider)
    missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
    return if missing.empty?

    raise ArgumentError,
          "Flag definition cache provider is missing required methods: #{missing.join(', ')}. " \
          'See PostHog::FlagDefinitionCacheProvider for the required interface.'
  end
end