[turnipdabeets]

💡 Motivation and Context

Part of #557 (4.0 plan: "Feat flag callback should be called if the API has an error as well, so the callback interface has to change"). Stacked on #873.

reloadFeatureFlags(_:) already runs its callback when a reload fails, but the callback takes no arguments, so there was no way to tell a failed reload from a successful one. It now receives a PostHogFeatureFlagsLoaded, the same type onFeatureFlags gets:

PostHogSDK.shared.reloadFeatureFlags { result in
    if result.errorsLoading {
        // The reload failed. result.variants holds the last known flags.
    }
}

• errorsLoading is true when the request fails (flags are the last cached ones), or when the SDK isn't set up (no flags, invoked right away).
• Quota-limited and partial (errorsWhileComputingFlags) responses report false, matching what onFeatureFlags reports today and posthog-js, which keys errorsLoading off the status code.

Public API change: breaking. Existing { ... } closures must become { _ in ... }, and the ObjC block now takes a PostHogFeatureFlagsLoaded *. See the api/posthog-ios.public-api.txt diff.

Spec: reload-feature-flags gives the canonical callback as (flags?, error?: Error) and leaves failure reporting SDK-specific. This diverges on purpose: it reuses the { flags, variants, errorsLoading } shape from the on-feature-flags spec, so both callbacks report the same thing. Spec update: PostHog/sdk-specs#99 (draft until 4.0 ships). No SDK currently passes an Error to the reload caller; the browser's errorsLoading boolean is the only real error signal across SDKs.

Wrapper SDKs: posthog-flutter calls reloadFeatureFlags(_:); PostHog/posthog-flutter#643 updates the closure. The React Native plugin doesn't call it.

Swift 6 concurrency: this callback will need @Sendable, and PostHogFeatureFlagsLoaded @unchecked Sendable (its variants is [String: Any]), as part of the concurrency work.

💚 How did you test it?

• New tests: the callback receives the loaded flags with errorsLoading == false; on a 500 it receives errorsLoading == true with the cached flags. The existing "not set up" test now checks errorsLoading and empty flags.
• make lint and make buildSdk (all 6 platforms) pass locally.
• make test locally: 963 tests, 4 failures, none in feature flags. The storage group-container test also fails on the base branch. The two exception-steps tests and the replay-queue test pass when run on their own, with and without this change.
• Not run locally: the iOS simulator test job.

📝 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.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

major changeset with migration notes, written by hand. Nothing publishes until release/4.0 merges to main.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code (Opus 5.5).
• Considered passing an Error instead of a Bool, and rejected it: no other SDK exposes a structured flags error, and reusing PostHogFeatureFlagsLoaded keeps the reload callback and onFeatureFlags consistent.
• Call-site updates in tests and examples are mechanical ({ → { _ in).

🤖 Generated with Claude Code

[github-actions]

posthog-ios Compliance Report

Date: 2026-10-07 18:37:41 UTC
Duration: 220658ms

⚠️ Some Tests Failed

44/45 tests passed, 1 failed

---

Capture Tests

⚠️ 28/29 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	2967ms
Format Validation.Event Has Uuid	✅	2714ms
Format Validation.Event Has Lib Properties	✅	2816ms
Format Validation.Distinct Id Is String	✅	273ms
Format Validation.Token Is Present	✅	2729ms
Format Validation.Custom Properties Preserved	✅	2790ms
Format Validation.Event Has Timestamp	✅	477ms
Retry Behavior.Retries On 503	✅	11635ms
Retry Behavior.Does Not Retry On 400	✅	4767ms
Retry Behavior.Does Not Retry On 401	✅	4774ms
Retry Behavior.Respects Retry After Header	✅	7776ms
Retry Behavior.Implements Backoff	✅	21817ms
Retry Behavior.Retries On 500	✅	9207ms
Retry Behavior.Retries On 502	✅	9303ms
Retry Behavior.Retries On 504	✅	8712ms
Retry Behavior.Max Retries Respected	❌	21323ms
Deduplication.Generates Unique Uuids	✅	2817ms
Deduplication.Preserves Uuid On Retry	✅	9207ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10405ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7772ms
Deduplication.No Duplicate Events In Batch	✅	2824ms
Deduplication.Different Events Have Different Uuids	✅	2725ms
Compression.Sends Gzip When Enabled	✅	2746ms
Batch Format.Uses Proper Batch Structure	✅	2757ms
Batch Format.Flush With No Events Sends Nothing	✅	330ms
Batch Format.Multiple Events Batched Together	✅	2854ms
Error Handling.Does Not Retry On 403	✅	4754ms
Error Handling.Does Not Retry On 413	✅	4638ms
Error Handling.Retries On 408	✅	8869ms

Failures

retry_behavior.max_retries_respected

Expected 4 requests, got 6

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	2850ms
Request Payload.Flags Request Uses V2 Query Param	✅	2765ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	2805ms
Request Payload.Flags Request Omits Authorization Header	✅	2695ms
Request Payload.Token In Flags Body Matches Init	✅	2684ms
Request Payload.Groups Round Trip	✅	2717ms
Request Payload.Groups Default To Empty Object	✅	2805ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	2752ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	2720ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	2696ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	2834ms
Request Lifecycle.No Flags Request On Init Alone	✅	87ms
Request Lifecycle.No Flags Request On Normal Capture	✅	400ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	5689ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	3329ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	3358ms

[dustinbyrne]

AI-assisted static review at 7fa61fcfa26ef6ad2339dc3ab8499beb29420da5. Regression scenarios were not executed.

[dustinbyrne]

The failed-reload snapshot and outdated closure-example concerns are addressed. The completion matches the published iOS 4.0 specification, and existing CI records the three new reload tests passing.

One optional test-ordering recommendation is inline. Consider also refreshing the stale specification/parity paragraph. The green compliance job still contains an unrelated capture-retry assertion failure; neither follow-up is a merge blocker for this change.

AI-assisted review.

[dustinbyrne]

[P2] Gate the first response so the reset regression exercises shared fan-out

Severity: MINOR; test reliability, not a production SDK defect.

The new test assumes the first failed reload remains in flight while both later callbacks register, but its mock responses have no delay or completion gate. MockPostHogServer.flagsResponseDelay defaults to zero (PostHogTests/TestUtils/MockPostHogServer.swift:75). The enclosing .serialized suite serializes tests, not the URLSession and RemoteConfig queues.

An allowed ordering is:

1. The first reload finishes before the second call.
2. The second reload starts and finishes its own request.
3. Its application callback calls reset().
4. The final reload completes after the cache has been cleared.

The final callback can then correctly contain empty variants, failing the test’s retained "string-value" assertion without violating the snapshot contract. The supported public calls involved are ordinary reloadFeatureFlags(_:) completions and reset(); the concern is their scheduling in this test, not incorrect production behavior.

This weakness is introduced by the new test; the merge base has no equivalent assertion. The governing contract is the test’s explicit claim that both later callbacks share one pending attempt. Current CI passing demonstrates a successful schedule, not enforcement of that precondition. No flaky failure was observed during this review.

Consider holding the first failed response until both pending callbacks have been registered, then releasing it. Keep the snapshot and cleared-getter assertions, and verify the intended request grouping. A controlled response gate is preferable to a fixed sleep.

Test sketch — not executed:

• Setup: Through the existing MockPostHogServer fixture, successfully load "string-value": "test", then return HTTP 500 for subsequent requests.
• Ordering demonstration: Await the first failed completion; issue and await the completion that calls reset(); then issue the final reload.
• Expected SDK result: The final completion reports failure with empty variants, and its getter returns nil.
• Result implied by the current test’s assertion: Its retained-variant assertion fails under that ordering, which the ungated asynchronous responses do not explicitly exclude.
• Corrected regression: Gate the first failed response; register both pending callbacks; release the gate; assert that the later completion retains "test" while its getter is nil after the preceding callback resets.
• Suggested validation: make test filter=reloadCallbackCoalescedFailureReset, using the controlled fixture.
• Execution limit: Neither sketch was executed during this static review.