FFL-2837: dynamic (rules-based) offline init plan - #1345
Open
btthomas wants to merge 7 commits into
Open
Conversation
Planning doc for rules-based (dynamic) offline feature-flag init in the React Native SDK: gaps to bridge in @datadog/flagging-core, explicit implementation steps, test plan, and risks/unknowns. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Resolve five of the plan's open questions: gate rules exposure on doLog (D3), keep two evaluation paths (D4), accept static-import bundle cost and reject dynamic import (D5), no offline opt-in gate for rules (D6), treat obfuscation/hashing as upstream (D7). Punt the flagging-core version/protobuf questions (Q1-Q2) to coordinate with upstream owners. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Point the Portable Flag Configuration and Offline Initialization references at their source Google Docs, keeping the local snapshot filenames noted alongside. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fold in the Obfuscation RFC (salted ONE_OF_SHA256 operators + binary structure) and the round-5/6 review findings. Obfuscation operators are absent from 2.0.1 and today silently fall back to DEFAULT, so unknown operators must be rejected as GENERAL, derived from the pinned OperatorType rather than an RN-maintained set. Sync SHA-256 is new bundle mass (Hermes+JSC). The hash protocol is unspecified and needs cross-SDK vectors plus malformed-condition load validation. Unsupported operators invalidate the rules branch only, keeping a valid precomputed sibling. Corrected the threat model and the full "what stays visible" UFC list. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds planning documentation for FFL-2837 (“dynamic/rules-based offline init”) in the React Native SDK, outlining intended behavior, dependency needs in @datadog/flagging-core, risks, and a proposed RN implementation + test plan.
Changes:
- Add a detailed technical plan covering architecture, upstream gaps, risk analysis, and step-by-step implementation/testing.
- Add a Simplified Technical English version of the plan for broader review/accessibility.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| dynamic_offline.plan.md | Detailed implementation plan, upstream dependency analysis, and risks/test plan for rules-based offline evaluation. |
| dynamic_offline_simplified.plan.md | Simplified Technical English version of the same plan for clearer cross-team review. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Use this existing flow: | ||
|
|
||
| ```text | ||
| configurationFromString -> setConfiguration -> evaluate |
| @@ -0,0 +1,772 @@ | |||
| # FFL-2837 — Dynamic (rules-based) offline init in dd-sdk-reactnative | |||
|
|
|||
| **Jira:** [FFL-2837 — Building Blocks API for dynamic offline init in ReactNative SDK](https://datadoghq.atlassian.net/browse/FFL-2837) | |||
Comment on lines
+9
to
+12
| - [Portable Flag Configuration RFC](https://docs.google.com/document/d/1OWNBtXtSk535VXqf-9fqsAmU9W8kpFLAwxYi2y1qyQQ/edit?pli=1&tab=t.0#heading=h.n52036mkzewg) (local snapshot: `./Portable-Flag-Configuration-RFC.md`, repo root, untracked) — defines the building blocks: `ConfigurationWire`, `configurationFromString/ToString`, `CoreProvider`, fetch fns, hooks. | ||
| - [Offline Initialization for Feature Flagging RFC](https://docs.google.com/document/d/1q1GlEbAgCGuO1OWfGbmKQkk5Oo-rE7YQwq29kMJJ4II/edit?pli=1&tab=t.0#heading=h.rnd972k0hiyer) (local snapshot: `./Offline-Initialization-for-Feature-Flagging.md`, repo root, untracked) — offline recipes built from those blocks; the operation is always `configurationFromString(wire) → provider.setConfiguration(config) → evaluate(...)`. | ||
| - [ConfigurationWire (Confluence)](https://datadoghq.atlassian.net/wiki/spaces/PANA/pages/5141725646/ConfigurationWire) — the published wire spec. Its **protobuf/base64** rules encoding is the intended target (see §2.5), even though the current code still uses JSON. | ||
| - **RFC: Obfuscation for rules-based client configs** (local: `./RFC_Obfuscation_for_rules-based_client configs.md`, 2026-07-10, first draft, one approval) — defines the obfuscation design for client rules: per-flag opt-in switch, salted `ONE_OF_SHA256`/`NOT_ONE_OF_SHA256` operators (server-compatible, engine-evaluated), binary structure format, and "document what's exposed". Answers most of our obfuscation open question — see G6/D7. |
Comment on lines
+1
to
+3
| # FFL-2837 — Dynamic Offline PR Stack | ||
|
|
||
| This document uses Simplified Technical English. |
sbarrio
requested review from
barboraplasovska and
sbarrio
and removed request for
barboraplasovska
July 24, 2026 07:06
sbarrio
reviewed
Jul 24, 2026
|
|
||
| FFL-2837 adds the **rules-based** (dynamic) offline flow: | ||
|
|
||
| - Customer loads a **rules-based** configuration (Universal Flag Configuration) via `setConfiguration` |
Contributor
There was a problem hiding this comment.
So setConfiguration can be used both to set a precomputed flag config and also the rules used to evaluate and compute it against a context?
Is there any particular reason for this and not have a specific and more clearly named function to set the rules?
I fear the API might end up being too broad for customers to clearly understand what does what and which precise calls they need to make to achieve the setup they want.
sbarrio
reviewed
Jul 24, 2026
|
|
||
| --- | ||
|
|
||
| ## 2. Current state of `@datadog/flagging-core` |
Contributor
There was a problem hiding this comment.
What's the expected size footprint of this package?, also, is this module stable?, we need to keep in mind that we don't do major releases that often so if any functionality of this module is to be exposed on the public SDK API we need to be sure that this does not introduce breaking changes often.
This was referenced Jul 24, 2026
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
dynamic_offline_pr_stack.plan.md:3
- The PR description says this PR adds
dynamic_offline.plan.md(detailed plan), but the branch currently addsdynamic_offline_pr_stack.plan.mdinstead. This mismatch makes it hard for reviewers to find the detailed plan document; either add/rename the detailed plan file as described, or update the PR description to match the actual files in the PR.
# FFL-2837 — Dynamic Offline PR Stack
This document uses Simplified Technical English.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull request stack
This description uses Simplified Technical English. Technical names and API names do not change.
Summary
This PR adds planning documents for FFL-2837. FFL-2837 adds dynamic rules-based offline feature flags to the React Native SDK. This PR does not change product code.
The branch starts from
blake.thomas/FFL-2666. That branch added precomputed offline support, the offline provider, andsetConfiguration.This PR adds these documents:
dynamic_offline_simplified.plan.md— the feature plan in Simplified Technical Englishdynamic_offline_pr_stack.plan.md— the PR-by-PR implementation planWhat the feature does
setConfiguration.setContextchanges the active context.One provider supports precomputed data and rules data. The SDK selects the path in this order:
Dependency state
The latest published
@datadog/flagging-coreversion is 2.0.2. Version 2.0.2 does not contain the new rules wire contract.The required changes are in progress:
rulesbranch, protobuf and base64 decoding, rules evaluation, per-flag validation, SHA-256 operators, and related compatibility fixes.CoreProvider. React Native uses it as an integration reference.The SDK does not import unpublished package code.
Wire encoding
The rules response uses protobuf and base64. The customer supplies the original opaque wire value.
configurationFromStringdecodes it after the required flagging-core release is available.The current draft implementation uses a temporary JSON compatibility wire. It has explicit
TODO(FFL-2837)markers. The implementation will remove that wire after PR #344 is published.Rules configurations cannot be serialized back to the wire format. The parsed object does not contain the original protobuf payload.
Obfuscation
The Obfuscation RFC uses salted
ONE_OF_SHA256andNOT_ONE_OF_SHA256operators and a binary structure. PR #344 implements these operators and synchronous SHA-256 evaluation.The remaining SDK work includes the final regular expression, size, and security policies.
Status
This PR is for plan review. The implementation PRs remain drafts while the upstream package and the remaining policies are incomplete.