feat: cache first initialization by luxscious · Pull Request #261 · DevCycleHQ/ios-client-sdk

luxscious · 2026-04-10T18:22:48Z

Summary

On cold start, initialize() now resolves immediately from a persisted config when one is available for the current user, and refreshes from the network in the background. The flash-of-defaults at every launch goes away, and transient network failures stop blocking the SDK from coming up.

Identity changes (identifyUser / resetUser) get matching error semantics: definitive auth/config errors invalidate the new user's cache and roll back to the previous user, while transient errors keep the cached values usable and refresh in the background.

What changed

Area	Where
Cache-hit fast path + background refresh	`DevCycleClient.setup` → `performBackgroundRefresh`
Definitive (400/401/403) vs transient API errors	`DevCycleService.APIError.isDefinitiveError`
Definitive error mid-refresh: keep cache, notify observers	`performBackgroundRefresh`
Definitive error mid-`identifyUser` / `resetUser`: evict that user's cache, restore previous user	`identifyUser` / `resetUser` + `Cache.clearConfigForUser`
Observers notified on every refresh (incl. SSE-pushed)	`onConfigUpdated` / `refetchConfig`

New public API

onConfigUpdated(_:) — refresh observer; the most recent pre-registration result is buffered and replayed once to a late registrant so handlers attached after setup() still see that first event.
hasUsableCachedConfig() — true between cache load and first successful refresh.

Inspiration / prior art

The definitive-vs-transient split and the broader cold-start shape are cross-referenced against OpenFeature ADR 0009.

Copilot

Pull request overview

Implements ADR 0009 “cache-first initialization” for the DevCycle client so cold starts can initialize from persisted config immediately and then refresh in the background, reducing “flash-of-defaults” while adding refresh observers and cache isolation support.

Changes:

Add cache-hit fast path in DevCycleClient.setup() with background refresh + onConfigUpdated(_:) observer API.
Introduce definitive error classification (400/401/403) and use it to control cache eviction/retention across refresh + user changes.
Add cache key namespacing support via DevCycleOptions.cacheKeyPrefix and update cache service behavior + tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
DevCycle/DevCycleClient.swift	Cache-first setup path, background refresh, definitive error handling, config update observers, and “CACHED” eval marking.
DevCycle/Models/Cache.swift	Adds per-user cache eviction and key prefixing for config storage keys.
DevCycle/Models/DevCycleOptions.swift	Adds `cacheKeyPrefix` option to namespace persisted cache keys.
DevCycle/Networking/DevCycleService.swift	Adds `APIError.isDefinitiveError` classification for ADR 0009 behavior.
DevCycle/Models/UserConfig.swift	Adds `EvalReason.withReason` to mark cached evaluations as `CACHED`.
DevCycleTests/Models/DevCycleClientTests.swift	Adds cache-first initialization + background refresh + observer behavior tests.
DevCycleTests/Models/DevCycleUserTest.swift	Makes TTL test less flaky by increasing TTL and wait time.
DevCycleTests/Networking/DevCycleServiceTests.swift	Updates cache mock to conform to expanded cache protocol.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

DevCycle/DevCycleClient.swift:601

resetUser() clears the anonymous id via self.cacheService (which may be prefixed), but then constructs anonUser via DevCycleUser.builder() which uses an unprefixed CacheService internally to generate/persist the anon id. With cacheKeyPrefix set this can repopulate the legacy ANONYMOUS_USER_ID key and produce a userId that doesn’t match the client’s namespaced storage, defeating multi-instance isolation. Consider generating the anon id using the client’s cacheService (same prefix) and building the DevCycleUser from that, or otherwise ensuring the builder uses the same namespace.

        let previousUser = self.lastIdentifiedUser
        let cachedAnonUserId = self.cacheService.getAnonUserId()
        self.cacheService.clearAnonUserId()
        let anonUser = try DevCycleUser.builder().isAnonymous(true).build()

        self.lastIdentifiedUser = anonUser

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

DevCycle/DevCycleClient.swift:600

When cacheKeyPrefix is used, resetUser reads/clears the anonymous ID via self.cacheService (which is prefixed), but then creates the new anonymous user via DevCycleUser.builder() which internally uses an un-prefixed CacheService() for getOrCreateAnonUserId(). This means resetUser can end up generating/using a global (unprefixed) anonymous ID and leave the prefixed anonymous ID unset, undermining multi-instance isolation and making the client’s cached anon-id state inconsistent. Consider plumbing the client’s cache namespace into anonymous user ID generation (e.g., inject a cache service/prefix into UserBuilder, or avoid UserBuilder’s persisted anon-id path inside resetUser).

        let previousUser = self.lastIdentifiedUser
        let cachedAnonUserId = self.cacheService.getAnonUserId()
        self.cacheService.clearAnonUserId()
        let anonUser = try DevCycleUser.builder().isAnonymous(true).build()

        self.lastIdentifiedUser = anonUser

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Auth/configuration errors at HTTP 400/401/403 won't recover from a retry, while network/server errors usually do. Splitting them lets cache-first init decide whether to keep the cached config usable on background-refresh failures and whether explicit identity changes should invalidate the new user's cache. Adds APIError.isDefinitiveError as the single source of truth for that distinction. Inspired by: OpenFeature ADR 0009. Made-with: Cursor

CacheService can already save and read a per-user config; the missing piece is invalidation. Adds CacheServiceProtocol.clearConfigForUser(user:) and its implementation so the client can drop a specific user's persisted config without touching anyone else's entries — used by the upcoming identifyUser/resetUser definitive-error paths. Made-with: Cursor

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

DevCycle/DevCycleClient.swift:623

In resetUser, the transient-error path restores the previous anonymous user ID in cacheService but does not restore lastIdentifiedUser to previousUser. Since lastIdentifiedUser was already set to the newly-generated anonUser (with a different userId after clearAnonUserId()), the client can end up with inconsistent state after a failed reset and future refreshes may use the wrong user context. Consider restoring lastIdentifiedUser (and any other derived state) on all error paths, not just definitive errors, or deferring the lastIdentifiedUser = anonUser assignment until after a successful fetch.

                    // Transient error: only restore the previous anon ID (matches pre-existing behavior).
                    if let previousAnonUserId = cachedAnonUserId {
                        self.cacheService.setAnonUserId(anonUserId: previousAnonUserId)
                    }
                    callback?(error, nil)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…ated observer Cold-start was previously gated on a network round trip — every launch paid full latency before any flag could be read. With this change, when a usable config is already persisted for the current user, setup() resolves immediately from cache and the network refresh runs in the background; on cache miss, the prior network-first behavior is preserved. - isConfigCached flag + hasUsableCachedConfig() public accessor - deliverInitializationComplete() helper standardizes setup completion on the main queue and drains queued config-completion handlers exactly once - performBackgroundRefresh() splits error handling: definitive (400/401/403) keeps cached values usable and notifies observers so the app can react; transient errors keep the cache silently - onConfigUpdated(_:) observer API with first-event replay buffer so handlers attached after setup() has already kicked off a background refresh still receive that first event (registration race) Inspired by: OpenFeature ADR 0009. Made-with: Cursor

Identity changes are user-initiated and definitive — silently serving another user's stale data on auth/config failure is the wrong default. This is the deliberate inverse of the background-refresh path, which keeps cached values usable on transient errors. - identifyUser: on definitive error (HTTP 400/401/403), clear the new user's persisted config and restore lastIdentifiedUser to the previous user. previousUser is captured at entry so any error path can roll back cleanly. - identifyUser: on transient error with a usable cached config, kick off a background refresh so the new user's data eventually reaches freshness without blocking the caller. - resetUser: on definitive error, clear the new anonymous user's cache, restore the previous anon user ID, and restore lastIdentifiedUser. Brings resetUser to parity with identifyUser. Inspired by: OpenFeature ADR 0009. Made-with: Cursor

Adds DevCycleClientTests coverage for the cache-first initialization path: - Cache-hit fast path resolves before network completion - Definitive auth error on background refresh keeps cached values usable in-session and emits onConfigUpdated(error:) - Transient error keeps cache silently with no event - identifyUser definitive error clears the new user's cache and restores the previous user - onConfigUpdated fires whether registered before setup() or after the refresh has already landed (registration-race regression) Also stabilizes DevCycleUserTest.testConfigCacheTTLRespected for loaded CI runners (100ms TTL was flaky; bumped to 2s). Made-with: Cursor

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

DevCycle/DevCycleClient.swift:626

In resetUser, when getConfig returns a non-definitive error you restore the previous anonymous user ID but you do not restore lastIdentifiedUser to previousUser before returning. That leaves the client in an inconsistent state (user remains the previous user, but lastIdentifiedUser is the new anonymous user), which can cause subsequent refetchConfig/background refreshes to run under the wrong user context. Restore lastIdentifiedUser (and any other mutated state) on all error/early-return paths where the reset does not actually complete.

                    if let previousAnonUserId = cachedAnonUserId {
                        self.cacheService.setAnonUserId(anonUserId: previousAnonUserId)
                    }
                    callback?(error, nil)
                    return

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

jsalaber

as per the ADR this pr should include the new cache-mode option

jsalaber · 2026-05-01T18:05:49Z

        }
    }
+
+    var isDefinitiveError: Bool {


what's definitive mean in this case?

Non-retryable server rejections, where retrying won't help.

jsalaber · 2026-05-01T18:07:45Z

        }

+        func clearConfigForUser(user: DevCycleUser) {
+            // TODO: update implementation for tests


should this be done as part of the pr?

Yea we can add it

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

luxscious force-pushed the ICP-2289-cache-first-initialization branch 7 times, most recently from 6d13e79 to 038d23b Compare April 14, 2026 14:48

luxscious mentioned this pull request Apr 14, 2026

feat: using cached values on initialization when available DevCycleHQ/ios-openfeature-provider#8

Draft

luxscious force-pushed the ICP-2289-cache-first-initialization branch 5 times, most recently from 49d422f to 9cbec58 Compare April 28, 2026 15:19

luxscious marked this pull request as ready for review April 28, 2026 15:23

luxscious requested a review from a team as a code owner April 28, 2026 15:23

Copilot AI review requested due to automatic review settings April 28, 2026 15:23

Copilot started reviewing on behalf of luxscious April 28, 2026 15:24 View session

luxscious force-pushed the ICP-2289-cache-first-initialization branch from 9cbec58 to dfcb351 Compare April 28, 2026 15:29

Copilot AI reviewed Apr 28, 2026

View reviewed changes

Comment thread DevCycle/DevCycleClient.swift

Comment thread DevCycle/DevCycleClient.swift

Comment thread DevCycle/Models/Cache.swift Outdated

luxscious force-pushed the ICP-2289-cache-first-initialization branch from dfcb351 to 236e412 Compare April 28, 2026 15:37

Copilot AI review requested due to automatic review settings April 28, 2026 16:05

luxscious force-pushed the ICP-2289-cache-first-initialization branch from 236e412 to 7dd8284 Compare April 28, 2026 16:05

Copilot started reviewing on behalf of luxscious April 28, 2026 16:06 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

Comment thread DevCycle/DevCycleClient.swift

Comment thread DevCycle/Models/Cache.swift

luxscious force-pushed the ICP-2289-cache-first-initialization branch from 7dd8284 to 8f843f4 Compare April 28, 2026 17:15

jsalaber reviewed Apr 28, 2026

View reviewed changes

Comment thread DevCycle/Models/Cache.swift Outdated

Comment thread DevCycle/Models/DevCycleOptions.swift Outdated

Copilot AI review requested due to automatic review settings April 29, 2026 14:32

luxscious force-pushed the ICP-2289-cache-first-initialization branch from 8f843f4 to 15c6a42 Compare April 29, 2026 14:32

Copilot started reviewing on behalf of luxscious April 29, 2026 14:33 View session

luxscious force-pushed the ICP-2289-cache-first-initialization branch from 15c6a42 to 68610a7 Compare April 29, 2026 14:33

luxscious requested a review from jsalaber April 29, 2026 14:36

Copilot AI reviewed Apr 29, 2026

View reviewed changes

Comment thread DevCycle/DevCycleClient.swift Outdated

Comment thread DevCycle/DevCycleClient.swift

Comment thread DevCycle/DevCycleClient.swift Outdated

Comment thread DevCycle/DevCycleClient.swift Outdated

Comment thread DevCycle/Models/Cache.swift Outdated

luxscious force-pushed the ICP-2289-cache-first-initialization branch from 68610a7 to b6cf252 Compare April 29, 2026 15:18

jsalaber approved these changes Apr 29, 2026

View reviewed changes

luxscious added 2 commits April 30, 2026 14:25

Copilot AI review requested due to automatic review settings April 30, 2026 17:32

luxscious force-pushed the ICP-2289-cache-first-initialization branch from b6cf252 to 06257a9 Compare April 30, 2026 17:32

Copilot started reviewing on behalf of luxscious April 30, 2026 17:32 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

Comment thread DevCycle/Models/Cache.swift

luxscious force-pushed the ICP-2289-cache-first-initialization branch from 06257a9 to a8c2241 Compare April 30, 2026 18:28

Copilot AI review requested due to automatic review settings April 30, 2026 18:49

luxscious force-pushed the ICP-2289-cache-first-initialization branch from a8c2241 to aed6f42 Compare April 30, 2026 18:49

Copilot started reviewing on behalf of luxscious April 30, 2026 18:50 View session

luxscious added 3 commits April 30, 2026 15:55

Copilot AI reviewed Apr 30, 2026

View reviewed changes

luxscious force-pushed the ICP-2289-cache-first-initialization branch from aed6f42 to 132b1c6 Compare April 30, 2026 19:09

jsalaber reviewed May 1, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings May 1, 2026 19:11

Copilot started reviewing on behalf of luxscious May 1, 2026 19:12 View session

Copilot AI reviewed May 1, 2026

View reviewed changes

Comment thread DevCycle/DevCycleClient.swift

Comment thread DevCycle/DevCycleClient.swift

Comment thread DevCycleTests/Models/DevCycleClientTests.swift

luxscious force-pushed the ICP-2289-cache-first-initialization branch from aa4cee7 to 132b1c6 Compare May 8, 2026 20:20

Conversation

luxscious commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

New public API

Inspiration / prior art

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jsalaber left a comment

Choose a reason for hiding this comment

Uh oh!

jsalaber May 1, 2026

Choose a reason for hiding this comment

Uh oh!

luxscious May 1, 2026

Choose a reason for hiding this comment

Uh oh!

jsalaber May 1, 2026

Choose a reason for hiding this comment

Uh oh!

luxscious May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

luxscious commented Apr 10, 2026 •

edited

Loading