Add option to exclude Realm file from iCloud backup

[danibonilha]

What, How & Why?

This PR adds a flag on Realm Config to exclude realm files from iCloud backup and also removes a reference from a guide that has been deleted.

This closes #4139

Draft discussion

@kraenhansen I'm starting this as a draft to make sure I'm on the right path, and to align some things:

1. In order to add this flag, some changes are required on @realm/core, to basically add exclude_from_icloud_backup on spec.yml and shared_realm.hpp, how is that coordinated ?

2. You mentioned testing might be tricky for this one, it's a bit concerning if it's too difficult because I might not have the bandwidth to do it, but I can give it a try if there are some really similar examples.

3. This implementation is enough to ENABLE excluding from backup, but it cannot be DISABLED once a realm file has been set with excludedFromBackup, since we are just checking for true on the flag and then setting the NSURLIsExcludedFromBackupKey key, there's no check to remove this key when the flag is false again. Which means that, if a realm file has been created with excludeFromIcloudBackup=false and then set to excludeFromIcloudBackup=true the file will be correctly excluded, but if the same file if set again to excludeFromIcloudBackup=false it will remain excluded. I see two ways to handle this:

• 1. Stick with this implementation and explain the behavior via docs;
• 2. Always check flag status and update files accordingly;

• Particularly I don't think there's much usage of setting this flag dynamically, so i'd probably go with the first option since realm does provide an easy way to copy a file with different configs if needed, although the second one is more flexible, it might take longer to be done as I believe I'd need to always be checking if the files already have the excludedFromBackup key set.

4. About the .md file on how to test this fix, where would that live?

Testing the fix

Generate the build files and test it on a sample react-native app on an IOS simulator, adding excludeFromIcloudBackup: true to the Realm configuration.

To validate if the file has the exclude backup attribute, you need to check the files attributes with xattr on your terminal, in order to do so you need the path of realm files from the simulator Documents' folder, you can easily get that first by running:

open `xcrun simctl get_app_container booted com.your.app.bundleId data`/Documents

This will open a Finder window with the files, you can just drag and drop it to the terminal after adding xattr

xattr [realm file simulator path]

if this command returns:

com.apple.metadata:com_apple_backup_excludeItem

It means the file has been successfully marked as excluded from backup 🎉
if it returns nothing, it means the file has no attributes therefore is not excluded from backup.

☑️ ToDos

• 📝 Changelog entry
• 📝 Compatibility label is updated or copied from previous entry
• 📝 Update COMPATIBILITY.md
• 🚦 Tests
• 📦 Updated internal package version in consuming package.jsons (if updating internal packages)
• 📱 Check the React Native/other sample apps work if necessary
• 💥 Breaking label has been applied or is not necessary
• 🔔 Mention @realm/devdocs if documentation changes are needed

[cla-bot]

Realm welcomes all contributions! The only requirement we have is that, like many other projects, we need to have a Contributor License Agreement (CLA) in place before we can accept any external code. Our own CLA is a modified version of the Apache Software Foundation’s CLA. Our records show that CLA has not been signed by @danibonilha. Please submit your CLA electronically using our Google form so we can accept your submissions. After signing the CLA you can recheck this PR with a @cla-bot check comment. The GitHub usernames you file there will need to match that of your Pull Requests. If you have any questions or cannot file the CLA electronically, make a comment here and we will be happy to help you out.

[kraenhansen]

First of all. Thank you so much for picking this up - impressive stuff 💙!

In order to add this flag, some changes are required on @realm/core, to basically add exclude_from_icloud_backup on spec.yml and shared_realm.hpp, how is that coordinated?

This can be done through a PR to https://github.com/realm/realm-core and and updating to the submodule of this repo to point to the PR commit in realm-core. But, since this won't be generally supported by the other SDKs I would rather that we keep changes to this codebase. A possible alternative is suggested in this comment: #6922 (comment). If you really want this to be supported generally across SDKs, I'd say the logic calling into setResourceValue should live in Realm Core too.

Always check flag status and update files accordingly

I like this idea 👍 I agree this would make it more flexible.

it might take longer to be done as I believe I'd need to always be checking if the files already have the excludedFromBackup key set.

Would it throw if you set it when it's already set? If not, I wouldn't be too worried of setting it while it's already set, as we'd expect it to be called once per app open.

About the .md file on how to test this fix, where would that live?

Perhaps a guide-testing-exclude-icloud-backup.md in https://github.com/realm/realm-js/tree/main/contrib 🤔

[danibonilha]

But, since this won't be generally supported by the other SDKs I would rather that we keep changes to this codebase.

Agreed, I've added a new implementation with a parameter

Would it throw if you set it when it's already set? If not, I wouldn't be too worried of setting it while it's already set, as we'd expect it to be called once per app open.

It does not throw, so I went ahead and update it to dynamically change based on the attribute

Perhaps a guide-testing-exclude-icloud-backup.md

I've created this file, but also added a script to make it easier to test, I have created for me but I just figured it would be helpful to have it in this project

Oh I also updated the ninja requirement, as I was having trouble running for android and it was because this package was missing, so I added a step with the OpenJDK.

[kraenhansen]

Awesome! I assume you've already verified this fixes the issue in your own (or some test) app?

[danibonilha]

Awesome! I assume you've already verified this fixes the issue in your own (or some test) app?

Yes I have, it's working perfectly on my app:

excludeFromIcloudBackup: true

excludeFromIcloudBackup: false

@kraenhansen I'm having issues though running the android app, but it might be my environment or something, is there a check on the CI that builds the android sample app ? Since there's no implementation there, just having it the app building should be enough.

[kraenhansen]

I'll take the Android version for a spin tomorrow, before merging this and then CI will run on the merge commit on main as well 👍 Unfortunately, we haven't figured out a way to let GitHub actions run on community PRs (as we need some secrets to start the test server).

[kraenhansen]

I reworded the note in the changelog and I ran the tests locally on Android, iOS and Node.js 👍
I'll go ahead with the merge and release of this 🎉

[kraenhansen]

I'm seeing some compilation errors on Node.js for Windows that I need to resolve before releasing this 😕 Stay tuned.

[danibonilha]

I'm seeing some compilation errors on Node.js for Windows that I need to resolve before releasing this 😕 Stay tuned.

Could it be related maybe to using unnamed parameters on node/platform.cpp ?

[kraenhansen]

Sorry about the wait on this one. Unfortunately the idea of a generalized after_realm_open function introduced some unforeseen build failures that I unfortunately don't have the bandwidth to investigate in depth at the moment.
Would you be willing to take a look and providing a review on #6927?