docs: add ADR 0009 for static-context cache-first local persistence

[jonathannorris]

Summary

• add ADR 0009 proposing local persistence with cache-first initialization for static-context OFREP providers
• on startup, providers load cached evaluations immediately so initial flag evaluations never return defaults, then refresh from the network in parallel
• define cache-hit and cache-miss initialization paths mapped to the OpenFeature provider lifecycle (PROVIDER_READY, PROVIDER_CONFIGURATION_CHANGED)
• cache key uses hash(targetingKey), no auth token dependency

Motivation

Every major vendor SDK (LaunchDarkly, Statsig, DevCycle, Eppo) uses cache-first initialization by default. Current OFREP static-context providers keep their cache in memory only, losing all state on restart. See vendor mobile SDK caching research for a detailed comparison.

Related

• Closes OFREP Static-Context Provider Local Persistence #65

Test plan

• not applicable; documentation-only change

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces an Architectural Decision Record (ADR) proposing a standard approach for web and mobile OFREP providers to enhance offline functionality. It aims to improve user experience by enabling the persistence of feature flag evaluations in local storage, ensuring that applications can operate and maintain consistent feature states even with intermittent network connectivity or after restarts.

Highlights

• Offline Resilience for OFREP Static-Context Providers: Proposes that web and mobile OFREP providers should persist their last successful bulk evaluation in local storage by default. This enables offline application startup and preserves feature state across restarts, addressing intermittent connectivity issues.
• Persistence Mechanism Details: Specifies that the persisted entry should include the bulk evaluation payload, ETag, metadata for matching the current provider instance (like OFREP endpoint and evaluation context), and the write time. It also outlines the initialization flow for loading from local storage.
• Consequences and Considerations: Discusses positive impacts like improved resilience and consistent offline behavior, as well as negative aspects such as increased provider complexity, potential for stale data, and security/privacy concerns with persisted data.

Changelog

• service/adrs/0009-localStorageForStaticContextProviders.md
  • Added a new Architectural Decision Record (ADR) proposing the default use of local storage for static-context OFREP providers to enable offline evaluation caching.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces ADR 0009, which proposes persisting static-context evaluations in local storage for web and mobile providers to improve offline capabilities. The ADR is well-structured and covers the main aspects of the proposal. My review includes a few suggestions to enhance the clarity and robustness of the proposed design, specifically regarding the handling of server errors during initialization, clarifying the purpose of the persisted timestamp, and making the initialization flow more explicit and unambiguous.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[lukas-reining]

Thanks @jonathannorris, left some feedback.
As you, I think this is a very important addition to the OFREP providers.

I have some thoughts regarding the cache key, which could also influence the whole concept due to the static context possibly also not being available as you said in open question no. 2.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[jonathannorris]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces ADR 0009, which proposes a cache-first local persistence strategy for static-context OFREP providers. The ADR is well-structured and detailed, covering the motivation, design, consequences, and implementation considerations. The proposed cache-first initialization aligns with industry best practices and addresses the 'flash-of-defaults' problem effectively. I have a couple of suggestions to improve the clarity and security aspects of the proposal.

[jonathannorris]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces ADR-0009, which proposes a cache-first initialization strategy for static-context providers using local storage persistence. It also updates the OpenAPI specification to support real-time change notifications via Server-Sent Events (SSE). Feedback indicates that the OpenAPI version 3.2.0 is non-standard and breaks compatibility, the itemSchema keyword in the webhook definition is invalid, and the ADR's proposed cache key needs namespacing and a specific hashing algorithm to prevent collisions. Additionally, the redundancy of new query parameters alongside standard HTTP cache headers should be addressed.

[jonathannorris]

@lukas-reining / @thomaspoignant take a look at this ADR when you get a chance