feat(distributed-cache): Add distributed cache support

[avasenin]

💡 Motivation and Context

Our tech stack is ruby/go and we would like to use https://posthog.com/docs/feature-flags/local-evaluation/distributed-environments

This PR adds support of this feature for go sdk.

💚 How did you test it?

Run tests full suite, please i used example to test out that its working as expected, fetch flags definitions and re-use it and next fetch if needed

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.
• I run examples manually with keys and make sure it works as it should

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Used existing 3 PRs in ruby/js/python as reference
• Decided to not bring Redis dependency and use file cache in examples to not increase footprint

[dustinbyrne]

hey @avasenin, thanks for putting this together! i've used an agent to compare this to other implementations and have some findings below. i'm around if you want any of these taken off your plate. otherwise i'll leave it to you!

[avasenin]

hey @dustinbyrne . i think i finished with all comments. let me know what do u think

[dustinbyrne]

thanks @avasenin! this is looking great. a couple of additional items as i'm looking through this. again, happy to take anything off your plate if you wish.

lastly - and i missed this on this first look - we require commit signing in order to merge to main. can you enable that and rebase/force push to sign your commits?

[dustinbyrne]

Keep provider cleanup ordered after active polling work

When ctx.Done() wins the select above, this still calls provider Shutdown even though the poller has not finished. Provider operations receive context.Background(), so client cancellation cannot stop them.

A public-client regression with a context-aware provider and a 20 ms CloseWithContext deadline reproduces Shutdown overlapping an active ShouldFetchFlagDefinitions, followed by GetFlagDefinitions after cleanup returns. Depending on the provider, that can use a closed connection or acquire a lock after cleanup already attempted to release it.

Consider keeping the caller's wait bounded while cancelling provider work, preventing further provider calls, and ensuring cleanup runs only after active polling finishes. Add a regression combining an active provider operation with an expiring shutdown deadline; the existing tests cover ordering and timeout separately.

[dustinbyrne]

Preserve the complete shared-cache payload rather than the evaluator model

Using []FeatureFlag makes the cache payload a projection of Go's evaluator model. That type omits fields such as flag id and version: I reproduced both disappearing when endpoint-shaped JSON is decoded into FlagDefinitionCacheData and marshalled again, as the file-cache example does. A different SDK or SDK version reading the same cache may need fields this evaluator does not use.

Consider using json.RawMessage at the provider boundary and retaining the original endpoint-shaped definition payload for publication, with typed decoding kept inside the SDK for validation and evaluation. Serializing the existing typed model into RawMessage would still lose those fields. Add round-trip coverage preserving id, version, and unknown metadata, including nested fields.