feat: Options parameter for Session.clearData API

[clavin]

Description of Change

Adds an options parameter to the recent Session.clearData API (#40983) to configure what types of data are cleared and scope the behavior to include or exclude specific origins.

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added options parameter to Session.clearData API.

Proposed API (Docs)

ses.clearData([options])

• options Object (optional)
  • dataTypes String[] (optional) - The types of data to clear. If undefined, will clear all types of data. See method details for possible values.
  • origins String[] (optional) - Clear data for only these origins. Cannot be used with excludeOrigins.
  • excludeOrigins String[] (optional) - Clear data for all origins except these ones. Cannot be used with origins.
  • avoidClosingConnections boolean (optional) - Skips deleting cookies that would close current network connections.
  • originMatchingMode String (optional) - The behavior for matching data to origins. Valid values are "third-parties-included" and "origin-in-all-contexts".

Returns Promise<void> - resolves when all data has been cleared.

Clears various different types of data.

dataTypes may include the following case-sensitive string values:

ℹ️ PR Note:

There are several other data types that the underlying content::BrowsingDataRemover interface supports. In particular, there are multiple categories that pertain to the privacy sandbox that I didn't include as I don't really understand them enough to know if they should be included in an Electron API like this. 🤷

Also, I'm not sure if some of these categories are relevant to electron, like downloads. I don't think Electron stores download information, but I included it just in the narrow chance we do.

I'm open to discussing and revising the list of supported data type categories!

• Background Fetch: backgroundFetch
• Cache: cache
• Cookies: cookies
• Downloads: downloads
• File Systems: fileSystems
• IndexedDB: indexedDB
• Local Storage: localStorage
• Service Workers: serviceWorkers
• WebSQL: webSQL

This method clears more types of data and is more thourough than the
clearStorageData method.

Note: Cookies are stored at a broader scope than origins. When removing cookies and filtering by origins (or excludeOrigins), the cookies will be removed at the registrable domain level. For example, clearing cookies for the origin https://really.specific.origin.example.com/ will end up clearing all cookies for example.com. Clearing cookies for the origin https://my.website.example.co.uk/ will end up clearing all cookies for example.co.uk.

For more information, refer to Chromium's BrowsingDataRemover interface.

Future Work

This may allow us to deprecate some other data clearing APIs we have:

• ✅ clearCache can be deprecated/reimplemented on top of this API.
• ✅ clearStorageData can be equivalently deprecated/reimplemented on top of this API.
  • One corner case is the quotas option, which there is no equivalent for in this proposed API; however, the "syncable" option is now deprecated and open to be cleaned up/removed in the future, and it is treated as the same as the other option. So, put short, this option no longer has a purpose and can be ignored. (To be clear: the other options of clearStorageData have equivalents in this API.)
  • The only other corner case is that the shadercache option would no longer be specifiable on its own, but would be part of cache. All other current storages options have direct mappings in this API.
  • Some of the equivalents in this API may have additional data cleaned up compared to the clearStorageData method, but I suspect these side effects are generally intended when calling a method to clear data.
• ❌ clearHostResolverCache cannot be deprecated or replaced by this API. The underlying Chromium API is not called as part of this API.
• 〰️ clearAuthCache cannot be easily replaced by this API, but is called as part of this API. While the underlying Chromium API powering this method is called by this API as part of clearing cookies, this API cannot be narrowed down to just calling only this method since clearing cookies has many other effects beyond clearing the auth cache.
• 〰️ clearCodeCaches cannot be easily replaced by this API, but is called as part of this API. While the underlying Chromium API powering this method is called by this API as part of clearing cache, this API cannot be narrowed down to just calling only this method since clearing cache has many other effects beyond clearing the code cache.

[zcbenz]

API LGTM

[samuelmaddock]

API LGTM

Love the docs and options validation 👍

[codebytere]

@clavin is there any more work to be done here or can this be merged?

[clavin]

@codebytere No more work, please do merge! 😄

[release-clerk]

Release Notes Persisted

Added options parameter to Session.clearData API.