Add distributed flag definition cache provider interface

[haacked]

Summary

This is a port of the FlagDefinitionCacheProvider interface implemented for posthog-python in this PR to posthog-ruby.

• Add a FlagDefinitionCacheProvider interface that enables multi-instance deployments (Kubernetes, serverless, load-balanced servers) to share feature flag definitions via an external cache (e.g., Redis), reducing redundant API calls to PostHog
• Integrate cache provider into the flag polling lifecycle: leader election via should_fetch_flag_definitions?, shared reads via flag_definitions, and cache writes via on_flag_definitions_received
• Include a Redis example implementation with Lua-based leader election and atomic lock management

Changes

• lib/posthog/flag_definition_cache.rb — new FlagDefinitionCacheProvider module with interface validation
• lib/posthog/feature_flags.rb — integrate cache provider into _load_feature_flags, extract _fetch_and_apply_flag_definitions, _apply_flag_definitions, and _store_in_cache_provider
• lib/posthog/utils.rb — add deep_symbolize_keys for round-tripping JSON-serialized cache data
• lib/posthog/client.rb — accept and forward flag_definition_cache_provider option
• examples/redis_flag_cache.rb — reference Redis implementation with leader election
• spec/posthog/flag_definition_cache_spec.rb — comprehensive tests covering cache hits, misses, error fallbacks, data integrity, and shutdown lifecycle

Error handling

All cache provider calls are wrapped in begin/rescue so cache failures never break flag evaluation:

• should_fetch_flag_definitions? errors → defaults to fetching from API
• flag_definitions errors → falls back to API fetch
• on_flag_definitions_received errors → logged, flags remain in memory
• shutdown errors → logged, shutdown continues

Test plan

• Run bundle exec rspec spec/posthog/flag_definition_cache_spec.rb
• Run full test suite bundle exec rspec
• Verify backward compatibility: existing clients without cache provider work unchanged

[Copilot]

Pull request overview

Adds an experimental distributed cache-provider interface for feature flag definitions so multi-instance deployments can coordinate polling (leader fetch) and share results via an external cache (e.g., Redis), reducing redundant calls to PostHog.

Changes:

• Introduces PostHog::FlagDefinitionCacheProvider interface + validation helper.
• Integrates cache-provider read/leadership/write/shutdown into FeatureFlagsPoller’s polling lifecycle.
• Adds deep symbolization utility + Redis example + comprehensive integration specs.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
lib/posthog/flag_definition_cache.rb	Defines the cache-provider interface contract and validation.
lib/posthog/feature_flags.rb	Adds provider hooks for leader election, cached reads, cache writes, and shutdown handling.
lib/posthog/utils.rb	Adds deep_symbolize_keys to normalize cached JSON data back to symbol keys.
lib/posthog/client.rb	Plumbs flag_definition_cache_provider option through to the poller.
lib/posthog.rb	Requires the new cache provider interface file.
examples/redis_flag_cache.rb	Provides a Redis + Lua leader-election reference implementation.
spec/posthog/flag_definition_cache_spec.rb	Adds tests for cache integration, fallback behavior, and shutdown lifecycle.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.