Skip to content

fix(flags): decode payloads cached by 3.x from the cached flag details - #935

Merged
turnipdabeets merged 5 commits into
chore/v4-remove-deprecatedfrom
fix/v4-cached-3x-payloads
Nov 5, 2026
Merged

turnipdabeets merged 5 commits into
chore/v4-remove-deprecatedfrom
fix/v4-cached-3x-payloads

Conversation

@turnipdabeets

@turnipdabeets turnipdabeets commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

4.0 decodes payloads strictly, so a malformed payload reads as null. But 3.x kept a malformed payload as its raw string in the payload cache. After the upgrade, 4.0 loaded that cache unchanged, so getFeatureFlagResult(key)?.payload returned the raw string until the first /flags response replaced it, or for as long as the app stayed offline. The migration guide called this out as a known gap.

The cached flag details (FLAGS) keep each payload exactly as the server serialized it. On cache load, 4.0 now decodes payloads from those details with the same strict decoder it uses on a /flags response, so cached and fresh payloads behave the same. It handles both the in-memory FeatureFlag objects and the maps that SharedPreferences gives back. Caches without flag details (from legacy v1 responses) keep their payload cache unchanged.

The migration guide's note about the gap is removed. No changeset is needed: the 4.0 changeset already describes strict payload decoding, and this fix makes cached payloads follow it.

💚 How did you test it?

  • New test: a 3.x-shaped cache, with flag details stored both as objects and as stored JSON maps, a raw hello payload and a valid sibling payload. After the upgrade, checkout reads null with its variant intact, and the sibling still decodes. It fails without the fix (expected null, but was: hello).
  • New test: a cache without flag details keeps its payloads.
  • PostHogRemoteConfigTest passes (124 tests), and spotlessCheck passes.
  • Device run with this PR, feat!: posthog-android 4.0 and posthog 7.0 #871, feat!: send events through capture v1 and add captureAi #881 and main merged together: a payload cached by 3.75.3 decoded to {plan=premium, seats=5} on the first 4.0 launch while offline.
  • CI: Build Job passes. The compliance workflow doesn't run for PRs into chore/v4-* until feat!: send events through capture v1 and add captureAi #881 merges its workflow change.

Merge note

This PR and #881 both edit docs/migration-3.x-to-4.0.md next to each other, so whichever merges second conflicts there. Keep both: drop the "A malformed payload cached by 3.x…" sentence and keep #881's $locale and $app_language section.

📝 Checklist

  • All commits are signed (see Commit signing)
  • 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.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code found this while checking the 4.0 flag API against PostHog/sdk-specs (feature-flag-cache: malformed payloads must not be exposed as raw strings). Versioning the payload cache or dropping it on upgrade were rejected because both lose cached payloads on an offline first launch. Rebuilding from the cached flag details loses nothing.

🤖 Generated with Claude Code

@turnipdabeets turnipdabeets self-assigned this Nov 3, 2026
@turnipdabeets
turnipdabeets requested a review from a team as a code owner November 3, 2026 18:11
turnipdabeets and others added 2 commits November 3, 2026 14:10
… fix/v4-cached-3x-payloads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`.

A malformed payload cached by 3.x can still read as the raw string after the upgrade, until the app's first `/flags` response replaces it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apps upgrading from 3.13 or older didn't cache flag details, so a malformed payload can still read as the raw string until the first /flags response. Could we keep a shorter version of the removed note for that case?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 An AI agent wrote this on behalf of @ioannisj.

+1, withPayloadsFromCachedFlags returns cachedPayloads untouched when there are no flag details, so those apps still get the raw string until the first /flags response.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added back a narrower note in f518a50, scoped to apps upgrading from 3.13 or older. There's no clean code fix for that case: 3.13 cached payloads already decoded, so a valid string payload like "hello" is stored as hello, the same shape as a malformed raw string. Without the flag details we can't tell them apart, and decoding or dropping them would break valid payloads for that first launch.

… fix/v4-cached-3x-payloads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@ioannisj ioannisj left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 An AI agent wrote this on behalf of @ioannisj.

No new findings: FLAGS and the payload cache stay in step through partial /flags merges, so decoding from the flag details is safe. Just a +1 on the open migration guide thread.


If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`.

A malformed payload cached by 3.x can still read as the raw string after the upgrade, until the app's first `/flags` response replaces it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 An AI agent wrote this on behalf of @ioannisj.

+1, withPayloadsFromCachedFlags returns cachedPayloads untouched when there are no flag details, so those apps still get the raw string until the first /flags response.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets
turnipdabeets merged commit a1aa0d3 into chore/v4-remove-deprecated Nov 5, 2026
11 checks passed
@turnipdabeets
turnipdabeets deleted the fix/v4-cached-3x-payloads branch November 5, 2026 15:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants