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

flag_definitions

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).

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.

on_flag_definitions_received(data)

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.

shutdown

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

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

Class Method Details

.validate!(provider) ⇒ Object

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



69
70
71
72
73
74
75
76
 
# File 'lib/posthog/flag_definition_cache.rb', line 69

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