Skip to content

fix(sdk): the Flutter SDK sends the user's attributes when it evaluates a flag - #2062

Open
amarkanday wants to merge 4 commits into
mainfrom
a1-flutter
Open

amarkanday wants to merge 4 commits into
mainfrom
a1-flutter

Conversation

@amarkanday

Copy link
Copy Markdown
Contributor

Resolves #438

Related: #2017 (SDK contract tests: a targeted flag for the iOS, Android and Flutter SDKs, from #438), the issue that holds the contract-test sentence of #438.

What changed

The Flutter SDK now sends the user's attributes when it evaluates a flag: GET /api/v1/feature-flags/evaluate/{key}?user_id=...&context=<percent-encoded compact JSON>, context after user_id. Before, the attributes were accepted and dropped, so a targeting rule on a user attribute never matched. A call with no attributes (none or {}) sends the same bytes as before. isEnabled gains {attributes}.

This is the last SDK of the mobile family, so it also finishes the shared-page sweep: with iOS and Android sending attributes, no native SDK is left that sends only the user id, so the limitations row, the guided-examples and demo sentences, and the four claims units that covered them are deleted whole, and video 4's description ends The demo uses the web SDK.

Branch a1-flutter, head d15bac5a, two commits on main: the change (e839f0e9) and d15bac5a (the page says unsendable attributes are logged nowhere). git diff --stat origin/main...HEAD: 18 files, +769/-177.

  • sdk/flutter/lib/src/client.dart, http_client.dart, cache.dart, sdk/flutter/test/client_test.dart
  • docs/sdk/flutter.md, sdk/flutter/README.md
  • docs/getting-started/limitations.md (row removed), docs/guides/guided-examples.md, demo/DEMO_GUIDE.md, demo/streampulse/README.md, and the four docs/_claims/**.toml units (deleted whole)
  • backend/tests/unit/api/test_documented_limits.py (NATIVE_SDKS, its test, _native_code and _CONTEXT deleted; Flutter moves to the "sends a context" list), backend/tests/unit/docs/test_deferred_sdk_pages.py, backend/tests/unit/showcase/test_site_walkthroughs.py (test renamed test_video_4s_description_names_no_native_sdk_limit)
  • frontend/src/content/videos.json (video 4's description; a site PR: T388, merges through the G5 train on the standing word, D454)

The choices, copied from the iOS pattern in Dart:

  1. Cache: EvaluationCache.get(user, key, {String? context}) (null means no check) and set(..., {String context = ''}). The in-flight key is user\u0000flag\u0000context.
  2. Request: query: {'user_id': userId, if (context.isNotEmpty) 'context': context}; a Dart map keeps insertion order, so user_id comes first. The context goes through _uri and Uri.encodeQueryComponent, as user_id already does (no new encoder).
  3. The offline key is unchanged; the stored answer is for any attributes and is read only after a non-404 failure; a 404 removes it and returns EvalResult.disabled.
  4. Key order: the attributes are written with json.encode, read back, and written again through a SplayTreeMap at every level, so the same attributes in another order (nested maps included) are one cache slot and one request.
  5. Unencodable attributes (a DateTime, NaN, a cycle): evaluateFlag returns EvalResult.disabled(key) before the cache, the dedupe and the offline store; nothing is sent, cached or logged, and the stored answer is not served.
  6. Errors name no query: the message is fixed text (Network error: the request timed out or Network error: the request failed), no chained error or URI field is kept, and _uri is inside the try, so an unparseable URL becomes the same ApiException.
  7. Decode helpers _serverQuery(Uri) and _serverContext(Uri) read a recorded URL as the server does: split on &, each pair at its first =, then Uri.decodeQueryComponent (it reads + as a space), then json.decode.

Merging main after iOS and Android (the rule recorded for this PR): take this PR's final state whole for the shared pages, the four claims files, videos.json and the showcase test (both the DESCRIPTION_FACTS string and the renamed test). In test_documented_limits.py take this side for the NATIVE_SDKS block, _native_code, _CONTEXT and the native test, keep _COMMENT, and make SENDS the union of the iOS, Android and Flutter entries. In test_deferred_sdk_pages.py SENDS_NO_CONTEXT loses ios, android and flutter; keep every SDK's own numbered section and its ..._on_the_<sdk>_pages test. Afterwards: python scripts/doc_claims.py check problems 0, the two backend files and backend/tests/unit/showcase green, and grep -rn "only the user id" over docs/, demo/ and frontend/src/content finds nothing.

How it was verified

No Flutter or Dart toolchain was available on the builder's machine, so no Dart line or test has been run by anyone yet. CI's flutter job (Flutter 3.19.6) is the first compile and the first run of every Dart line here; the Dart was read as Dart 3 / Flutter 3.19 by the builder and by the reviewer, who found no compile error or run-time failure by reading.

Measured at d15bac5a unless another sha is given (records: handback-builder-A1-flutter, -flutter-2; review review-a1-flutter, at e839f0e9):

  • The two backend files (test_documented_limits.py, test_deferred_sdk_pages.py): 348 passed (main: 342; 3 native[...] cases removed, 9 added). backend/tests/unit/docs and showcase together: 5081 passed.
  • python scripts/doc_claims.py check: problems 0. mkdocs build --strict: exit 0. ruff check / ruff format --check on the pin file: clean. DCO ok for both commits. The secret scan: no findings.
  • Name-only diff against backend/ modules/ frontend/ pyproject.toml lists exactly the two backend test files, test_site_walkthroughs.py and videos.json; nothing under modules/, .github/, scripts/ or backend/app, and no pyproject.toml.
  • Test count: the baseline is 70 (51 + 14 + 5); client_test.dart now has 82 tests, so 101 are expected in CI (+31). The job result and the exact count come from CI.
  • Tampers at e839f0e9: the marker removed from client.dart fires 3 gates; a pinned Dart test renamed fires its pin; the old note put back fires test_the_old_flutter_note_is_gone_from_both_pages; flutter put back in SENDS_NO_CONTEXT fires 4 tests; Android's ; Flutter sends only the user id to flags wording put back in videos.json fires the video test (1 failed, 57 passed; 58 passed restored).
  • At e839f0e9: the wide DB-free sweep gave 2 failed, 25930 passed, 181 skipped, 168 errors; the same 170 ids fail on origin/main (the 168 need PostgreSQL; the 2 are the pep440 pair, No module named 'packaging'). Not re-run at d15bac5a (docs text and one pin string changed).
  • CI-only plant branches (one commit each on the PR head, never PR heads): the old code (without the one test that cannot compile there, regression #438: isEnabled passes the attributes on, because isEnabled has no attributes: on main), the context unencoded and %2B written as +. Their results are not in yet.
  • Review: review-a1-flutter approved e839f0e9 with three optional nits; d15bac5a implements the page-wording nit (N3) and has no review record of its own. The body carries the merge rule from nit N2.

Checklist:

  • Tests run locally and green: the Python gates are green; the Dart tests have not been run (no Dart locally)
  • make lint clean: not run as a whole; ruff clean on the pin file; CI's Frontend Tests must show success at the final head before merge

Not verified: every Dart line and test; V3a's exact URL (%7B%22q%22%3A%22a%2Bb%26c%3Dd%23e+f%C3%A9%22%7D, written from encodeQueryComponent's rules and not measured); that Uri.parse throws for a non-numeric port (the unparseable-URL test); NaN handling of json.encode on Flutter web; a device; the real server; the frontend suite.

Regression test

  • This is a bug fix, and it adds a test that fails without the fix:
    sdk/flutter/test/client_test.dart -- regression #438: evaluateFlag sends the attributes as context after user_id, regression #438: a targeting rule on attributes matches and regression #438: isEnabled passes the attributes on
  • Not a bug fix

On main's client.dart and http_client.dart the evaluate and rule tests fail on assertions (the path lacks &context=...; the rule does not match), and the isEnabled test does not compile because isEnabled has no attributes: there. That is the builder's and the reviewer's reading; the old-code plant branch is what runs it in CI.

Risk and rollback

This changes the SDK's request to the public flag-evaluation route for callers that pass attributes, and removes a documented limit from the public docs. If it is wrong, flag calls with attributes answer from the wrong context or fail; revert this PR to undo it, which also restores the limitations row and the claims units. Nothing changes on the server, and no release is cut here. It merges after the iOS and Android PRs.

  • No migration, or every migration here is expand-only

🤖 Generated with Claude Code

https://claude.ai/code/session_011kqtSDC7sd5ue3m6LuwdXV

amarkanday and others added 3 commits November 16, 2026 03:42
…es a flag

evaluateFlag took an attributes argument and ignored it: the request was
GET /api/v1/feature-flags/evaluate/{key}?user_id=... with nothing else, so a
flag rule on an attribute never matched from a Flutter app, while the same
attributes went out as the context of an experiment assignment.

evaluateFlag now sends them as `context`, after `user_id`, through the
encoder `user_id` already uses (Uri.encodeQueryComponent), and isEnabled gains
the same named argument. With no attributes, or an empty map, the request is
the one sent before, byte for byte.

- The cache keeps one entry per user + flag together with the context it was
  answered for; a call with other attributes asks the server again and
  replaces it. The keys of every object are sorted, so the same attributes in
  another order are one cache slot. The in-flight key carries the context.
- The offline store key is unchanged: the last answer for any attributes,
  read only when the server cannot answer, removed by a 404.
- Attributes that cannot be written as JSON give the disabled answer before
  the cache, the dedupe and the offline store; nothing is sent.
- A network error's message is fixed text: the transport error's own text
  names the request URI, query included, so none of it is kept.

This completes #438 for the native SDKs, so the shared sentences, the
Limitations row and their claims units go, with the native-SDK source test
and NATIVE_SDKS, and video 4's description no longer names a native limit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011kqtSDC7sd5ue3m6LuwdXV
Signed-off-by: amarkanday <a.markanday@gmail.com>
…here

When the attributes cannot be written as JSON, evaluateFlag returns the
disabled answer and sends nothing; the SDK also logs nothing, so the disabled
answer is the only sign. The page and the README now say so, and the sentence
pin carries the same text.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011kqtSDC7sd5ue3m6LuwdXV
Signed-off-by: amarkanday <a.markanday@gmail.com>
Main took the Ruby, PHP, Edge and Elixir SDK changes since this branch was
cut. They change the same two test files as this change, so the merge
conflicts in exactly those two, and the resolution keeps both sides' entries
(MERGE-RULES-A1 "Server family" union and the Flutter section's union
sentences; merge, no rebase, no force push). iOS and Android have not merged,
so they stay where main has them.

- backend/tests/unit/api/test_documented_limits.py: SENDS is the union of
  main's ruby, php, edge and elixir entries and Flutter's; DOES_NOT_SEND loses
  flutter and keeps ios and android.
- backend/tests/unit/docs/test_deferred_sdk_pages.py: SENDS_NO_CONTEXT loses
  flutter and keeps android and ios; Flutter's section 9 and its claim-pattern
  test are kept beside the Ruby, PHP, Edge and Elixir sections and tests. The
  file is main's, with exactly this change's three insertions applied.

No other file conflicted, so the Flutter section's nine take-whole files and
the showcase test did not come into play: nothing outside the two files'
shared lines changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011kqtSDC7sd5ue3m6LuwdXV
Signed-off-by: amarkanday <a.markanday@gmail.com>
@amarkanday amarkanday added the bug Something isn't working label Nov 19, 2026
Brings the Flutter branch up to main 9448fb3, which holds the iOS (#2045),
#1747 (#2046) and Android (#2074) changes. Twelve files conflicted. Main also
changed some of them for unrelated reasons (the AWS CDK two-step sign-in row
and its tests, the front matter of the Limitations page), so each is resolved
from main's version with this branch's own change applied on top, not by taking
this branch's whole file.

Main's version plus this branch's change (ten files; where the iOS or Android
edit and this branch's edit touched the same sentence, this branch's wording
wins, because it deletes the sentence):
- demo/DEMO_GUIDE.md
- demo/streampulse/README.md
- docs/guides/guided-examples.md
- docs/getting-started/limitations.md
- docs/_claims/demo/DEMO_GUIDE.md.toml
- docs/_claims/demo/streampulse/README.md.toml
- docs/_claims/docs/getting-started/limitations.md.toml
- docs/_claims/docs/guides/guided-examples.md.toml
- frontend/src/content/videos.json
- backend/tests/unit/showcase/test_site_walkthroughs.py

The union of both sides:
- backend/tests/unit/api/test_documented_limits.py: SENDS holds the iOS,
  Android and Flutter entries beside the server SDKs already on main. The
  native-SDK block, its helpers and its test stay deleted. Every SDK now
  sends the context, so DOES_NOT_SEND is empty and is deleted with the code
  that only read it; the classification test keeps checking SENDS.
- backend/tests/unit/docs/test_deferred_sdk_pages.py: SENDS_NO_CONTEXT is
  empty and is deleted with the two tests that only read it and the
  assertions that an SDK is not in it; the check that every deferred SDK
  sends the context stays, and fails naming the SDK that stops. Every SDK's
  own section and page tests are kept, and this branch's section is numbered
  10, so that it no longer shares a number with the Android section.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NpxPyav9uBxNuiXsDvD8qn
Signed-off-by: amarkanday <a.markanday@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Native mobile SDKs (iOS, Android, Flutter) never send user attributes on flag evaluation, so flag targeting cannot match

1 participant