Skip to content

[FSSDK-12251] feat: allow custom directory for DataStoreFile and DefaultEventDispatcher - #668

Merged
Muzahidul Islam (muzahidul-opti) merged 9 commits into
masterfrom
muzahidul/datastore-custom-directory
Oct 27, 2026
Merged

Muzahidul Islam (muzahidul-opti) merged 9 commits into
masterfrom
muzahidul/datastore-custom-directory

Conversation

@muzahidul-opti

Copy link
Copy Markdown
Contributor

Summary

Internal continuation of #612 by Michael Artes (@asmeili). Their commits are kept as-is, with authorship preserved, and one commit on top makes the change source-compatible with 6.x.

  • DataStoreFile: new convenience init(storeName:directory:async:) stores the file in any FileManager.SearchPathDirectory
  • DefaultEventDispatcher: new convenience init(batchSize:dataStoreName:dataStoreDirectory:timerInterval:maxQueueSize:) puts the event-queue file in a custom directory
  • DefaultDatafileHandler: no change needed. Override createDataStore(sdkKey:) and return DataStoreFile<Data>(storeName: sdkKey, directory: .applicationSupportDirectory)

Why: DataStoreFile defaults to .documentDirectory on iOS, so the SDK's datafile cache and event-queue files show up in the user's Files app. Apps can now move them to .applicationSupportDirectory, for example:

let dispatcher = DefaultEventDispatcher(dataStoreDirectory: .applicationSupportDirectory)
let optimizely = OptimizelyClient(sdkKey: key, eventDispatcher: dispatcher)

What changed vs. #612 and why

The original shape broke public API in a minor release. CI's api_breaking_changes job (diagnose-api-breaking-changes) blocks that:

#612 Breaks This PR
case file → case file(directory: ... = nil) backingStore: .file no longer compiles; the enum loses synthesized Equatable/Hashable, so == .memory fails DataStoreType unchanged; the directory is passed to a new init
DataStoreFile.init(storeName:async:) made convenience subclasses calling super.init(storeName:) fail ("must call a designated initializer") the existing init stays designated
new designated init(s) on open classes flagged by the API checker: subclasses lose inherited convenience inits new inits are convenience: they call the existing designated init, then set the custom store

Supporting internal changes:

  • DataStoreFile.url: public let → public private(set) var. It is still read-only publicly.
  • DefaultEventDispatcher.eventQueue: internal let → private(set) var

These let the convenience inits replace the default store. The throwaway default store costs nothing because creating it does no disk I/O.

Test plan

  • swift package diagnose-api-breaking-changes origin/master → No breaking changes detected in Optimizely. Both refactor: Added ability to inject custom directory for DataStoreFile #612's shape and an internal-designated-init variant failed this check.
  • xcodebuild test (iOS 27 sim): EventDispatcherTests, DataStoreTests, DatafileHandlerTests, 40/40 passed
  • Existing DataStoreTests.testFileStoreCustomDirectory (from refactor: Added ability to inject custom directory for DataStoreFile #612) covers DataStoreFile in Application Support
  • Added EventDispatcherTests.testEventDispatcherFileCustomDirectory: the dispatcher's queue file is created in Application Support
  • testEventDispatcherFile is back to using .file, which checks the original call site still compiles
  • SwiftLint clean on changed files

Issues

🤖 Generated with Claude Code

artesmichael and others added 7 commits October 16, 2026 21:27
…ible

Rework #612 so it adds API without breaking 6.x users:
- Restore `DataStoreType.file` (no associated value) so `.file` and `==` keep compiling
- Keep `DataStoreFile.init(storeName:async:)` designated so subclasses can call super.init
- Expose the directory via new convenience inits on DataStoreFile and DefaultEventDispatcher
  (new designated inits on open classes are flagged by diagnose-api-breaking-changes)
- Add a test for the dispatcher custom-directory path

Co-authored-by: artesmichael <michael.artes@icloud.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coveralls

Coveralls (coveralls) commented Oct 16, 2026 •

Copy link
Copy Markdown

Coverage Status

No base build to compare — muzahidul/datastore-custom-directory into master

@Mat001 Matjaz Pirnovar (Mat001) 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.

API-compat strategy (convenience inits, no enum change) is well done and the zero-IO throwaway-store claim checks out. One blocker: DataStoreFile never creates the target directory, and .applicationSupportDirectory does not exist by default on iOS — the feature's headline use case silently drops events/datafile writes.

Comment on lines +51 to +56
public convenience init(storeName: String, directory: FileManager.SearchPathDirectory, async: Bool = true) {
self.init(storeName: storeName, async: async)
if let url = FileManager.default.urls(for: directory, in: .userDomainMask).first {
self.url = url.appendingPathComponent(storeName, isDirectory: false)
}
}

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.

The target directory is never created, and .applicationSupportDirectory — the directory this feature exists to enable — does not exist by default on iOS. Writes there fail silently and events are dropped.

FileManager.urls(for:in:) returns the URL whether or not the folder exists on disk. iOS auto-creates Documents, tmp, and Library/Caches, but not Library/Application Support — the app must create it. The old code only used .documentDirectory (always present), so this never mattered before.

Downstream, writeData uses Data.write(to:options:.atomic), which does not create intermediate directories and throws if the parent is missing. saveItem swallows that into a log line, so the failure is silent:

} catch let e {
    self.logger.e(e.localizedDescription)   // event dropped, count stays 0
}

Failure scenario (the PR's own example):

let dispatcher = DefaultEventDispatcher(dataStoreDirectory: .applicationSupportDirectory)

On a real app where Library/Application Support hasn't been created, every eventQueue.save throws and is swallowed, count stays 0, flushEvents finds nothing — analytics events are silently lost. The datafile-cache path (createDataStore → DataStoreFile(directory: .applicationSupportDirectory)) fails the same way.

Why the tests miss it: both new tests pre-create the directory before using the store (DataStoreTests.testFileStoreCustomDirectory calls createDirectoryIfNeeded(...); EventDispatcherTests.testEventDispatcherFileCustomDirectory calls FileManager.default.createDirectory(at: dirUrl, withIntermediateDirectories: true)), so they only exercise a precondition the feature never establishes itself.

Proposed fix:

// convenience on purpose: any new designated init on an open class is an API break
public convenience init(storeName: String, directory: FileManager.SearchPathDirectory, async: Bool = true) {
    self.init(storeName: storeName, async: async)
    if let dirUrl = FileManager.default.urls(for: directory, in: .userDomainMask).first {
        // Application Support (unlike Documents) is not guaranteed to exist on iOS;
        // create it so writes don't silently fail and drop events.
        try? FileManager.default.createDirectory(at: dirUrl, withIntermediateDirectories: true)
        self.url = dirUrl.appendingPathComponent(storeName, isDirectory: false)
    }
}

And drop the createDirectory pre-steps from the new tests (or add a variant without them) so they actually prove the store is self-sufficient.

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.

Good catch, thanks. Fixed in 6999d38.

  • The convenience init now resolves the directory with FileManager.default.url(for:in:appropriateFor:create: true). This is Foundation's built-in way to create a standard directory if it's missing.
  • One difference from your suggestion: if creating the directory fails, the store keeps its default location (Documents), so events are still saved and not dropped. With try? createDirectory followed by always setting url, events would still be dropped in that rare case.
  • Tests: removed the pre-create steps from testFileStoreCustomDirectory and testEventDispatcherFileCustomDirectory. I couldn't use Application Support to prove the directory gets created, because these tests have no host app. Application Support resolves to the simulator device's shared folder, which always exists and can't be deleted. So I added testFileStoreCreatesMissingDirectory, which uses .autosavedInformationDirectory (missing on a fresh simulator). It failed before the fix and passes with it.
  • DataStoreTests, EventDispatcherTests, DatafileHandlerTests: 41/41 passed. diagnose-api-breaking-changes origin/master: no breaking changes.

Could you re-review?

@Mat001 Matjaz Pirnovar (Mat001) 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.

Looks good, one comment.

Application Support isn't guaranteed to exist on iOS, and Data.write
doesn't create parent directories, so writes failed and saveItem
swallowed the error, silently dropping queued events.

Resolve the directory with url(for:in:appropriateFor:create: true).
If creation fails, the store keeps its default location.

Tests no longer pre-create the directory; add a test against a
directory that doesn't exist yet.

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

Copy link
Copy Markdown

Pipelines

❌ Errors

Your PR has failed checks. Please review the issues below and take necessary action before merging.

🚦 1 Pipeline job failed

Swift | unittests / unittests (27.0, iPhone Air, OptimizelySwiftSDK-iOS, iphonesimulator, iOS Simulator, iOS) — 🔄 Retry may pass, looks flaky

View in Datadog · View in GitHub Actions

Useful? React with 👍 / 👎

This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 6999d38 | Docs | View more details | Give us feedback!

@Mat001 Matjaz Pirnovar (Mat001) 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.

Your fix is actually better than my proposed try? createDirectory + unconditional self.url = …. Because the create: true call is inside the if let, a creation failure (nil) leaves self.url at the Documents default set by self.init(storeName:async:) — so in the rare failure case events still get persisted to Documents instead of being dropped. My version would have reassigned url even when createDirectory failed, reintroducing the silent-drop. His gracefully degrades.

@muzahidul-opti
Muzahidul Islam (muzahidul-opti) merged commit b48c241 into master Oct 27, 2026
12 of 13 checks passed
@muzahidul-opti
Muzahidul Islam (muzahidul-opti) deleted the muzahidul/datastore-custom-directory branch October 27, 2026 14:38
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