feat: Session#clearData API

[clavin]

This PR adds a new clearData API for clearing out data created by Electron to the Session class.

See the API proposal below for more details, considerations, and future work.

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: clearData method added to Session.

Proposed API

ses.clearData()

This method corresponds to invoking Chromium's BrowsingDataRemover, which can clear many types of data, inlcuding:

• Cookies
• Cache
• Indexed DB
• Local storage
• WebSQL
• Service workers
• Background fetch
• And many others

At present, this method attempt to clear all categories. See the "Future work" section for more information about how this API is designed to be extended.

This method returns a Promise<void> that resolves once the data is cleared successfully, or rejects if any categories of data failed to be cleared with an error.

const win = new BroserWindow(...);
const { session } = win.webContents;

// Attempt to clear all browsing data
try {
  await session.clearData();
} catch (err) {
  console.error("Failed to clear data:", err);
}

Prior Art

While working on this feature, I discovered Chrome exposes this functionality via an extension API: chrome.browsingData extension API. (See alternatives below for more discussion on this existing API.)

Future Work

This API is designed to be extended in the future with an optional options object parameter. The options will allow users to filter what kinds of data to clear, based on the options available from Chromium's BrowsingDataRemover API. This may also allow us to deprecate some other methods whose functionality become completely subsumed by this expanded method behavior, using the right options.

With this richer configuration, we can also return richer information on the error object in the failure case, like which categories of data failed to be removed.

Alternatives

Multiple, more granular methods

Instead of creating one big supermethod with an options object, we could choose to break it up into individual smaller methods (clearCacheData, clearCookiesData, clearIndexedDBData, etc.). We may opt to also keep the general clearData as a shortcut for calling all of these methods together, effectively clearing all data.

The downside is that it's not clear what this granularity would give us. The API surface for Session would become even more noisy.

Different name

The original proposal mirrored the underlying API name: clearBrowsingData. It was decided that it would be more clear to name this method simply clearData. You don't really "browse" with Electron apps, which begs the question of what "browsing data" would be for Electron.

Not rejecting

Instead of rejecting and potentially throwing errors for what might not be a critical issue, we could make the return value of this method a Promise<ClearedDataInfo> that contains information about what categories of data were successfully cleared (not sure that data is useful) and which ones failed.

Reuse the extensions API

We could try to go down the route of exposing the existing chrome.browsingData extension API instead of implementing our own API on top of the same functionality.

However, this approach has some notable disadvantages:

• Electron's support of Chrome's extensions API seems to be provided as a compatibility layer for reasonable, existing Chrome extensions to work with Electron; whereas, this functionality is useful outside of extension compatibility and it is unlikely that extensions using the Chrome API are built with Electron's use case in mind.
• The extension API may not be compatible with Electron, or at least parts of it would not translate to Electron properly.
• We are bound to Chrome's API surface and design, which is built with a different model of trust and a different scope of power from Electron.

[samuelmaddock]

You don't really "browse" with Electron apps, which begs the question of what "browsing data" would be for Electron. We could change the name of the method to better suit Electron apps. Perhaps just clearData or another name that fits better.

The bit about browsing is a good point and I like the idea of using the name clearData. One thing that helps sway me is the BrowsingDataRemoverImpl::RemoveImpl code allows the embedder application to delete its own data—meaning browsing data plus whatever else we want to cleanup in Electron.

[ckerr]

This API is designed to be extended in the future with an optional options object parameter. The options will allow users to filter what kinds of data to clear, based on the options available from Chromium's BrowsingDataRemover API. This may also allow us to deprecate some other methods whose functionality become completely subsumed by this expanded method behavior, using the right options.

This is a nice idea @clavin! Thanks for the proposal!

Would it be possible to outline what the full API would look like at endgame? I'm curious about what options would be exposed and what methods would be deprecated.

[clavin]

I discovered Chrome exposes an API like the one proposed here via its extensions APIs. I updated the main post with more information and discussion about it.

[clavin]

Would it be possible to outline what the full API would look like at endgame? I'm curious about what options would be exposed and what methods would be deprecated.

@ckerr While answering this question, I discovered the chrome.browsingData extension API, which looks similar to what I had in mind. (See the updated main post for more discussion about that API.)

The future work on this proposed API would look similar to that existing API, but with a change in shape:

The method signature would be simply ses.clearBrowsingData([options]). options is an optional object. When absent, the method should work as it does now in this proposal: clearing everything. The options it would accept would be something like this:

• dataTypes: The categories of data that should be cleared. This is similar to the dataToRemove parameter and the DataTypeSet in the existing chrome.browsingData extension API. Instead of being an object with all boolean values, this option would accept just an array of strings. E.g. dataTypes: ['cache', 'cookies', 'indexedDB', 'localStorage'].
  • We would have our own set of data type categories that make sense for Electron. For example, the chrome.browsingData category 'passwords' would not be present in Electron as it doesn't store that information.
• origins and excludeOrigins: only one of these two options is allowed. They indicate whether to clear only specific origins or to clear all except specific origins, and it specifies those origins as well. This design is borrowed from the chrome.browsingData extension API.
• There should be more options to control the behavior of the options above, like avoidClosingConnections (which is a content::BrowsingDataRemover::DataType, but acts more like a modifier than a category in its own right) and originMatchingMode (corresponding to content::BrowsingDataFilterBuilder::OriginMatchingMode). There may also be others that are discovered while taking on that future work.

(As an aside, the originTypes and since options from the chrome.browsingData API are not expected to show up in near-future work on this proposed API. There's no technical reason they can't be added in the future, as the API surface is capable of supporting more options; however, they either need some work to fit into Electron's API and/or I don't suspect they will be important enough to Electron developers to include in the next iteration.)

[samuelmaddock]

It looks like v8::Error can be cast to an object to set additional properties according to the v8 tests.

Maybe the failed data types could be set as a custom property on the error object. It would be a little unusual though as Electron doesn't do this anywhere else.

[clavin]

I had that behavior in a previous revision, and then I realized that it would be better if the failed data types was a set or array of data categories as strings. It would be far more useful to JS code in that form. That mapping doesn't really exist right now but might in a future revision.

[clavin]

I think there are two approaches to pick from:

1. Keep this error as-is for now, and extend it in the future when the mapping from data types to category strings exists.
2. Same as (1) where we add a simple field in the future, but attach an errorCode field now with the raw numerical value of failed_data_types.

There's some rough edges with exposing this raw value to JS though. It's a 64-bit unsigned integer, which could theoretically go beyond the 53-bit limit of normal JS numbers, though there are barely half that number of flags right now. The safe route would be to expose it as a bigint, but that could be confusing.

[zcbenz]

What is the difference between this and the clearStorageData API?

[clavin]

@zcbenz The clearStorageData API calls StoragePartition::ClearData directly. The Chromium API backing this proposed clearBrowsingData API (content::BrowsingDataRemover) is more general and includes options for calling StoragePartition::ClearData, among others. For example, a data category not currently covered by existing APIs like clearStorageData is some networking history, which is only called via content::BrowsingDataRemover. I suspect there are others that fall into this category too.

[zcbenz]

API LGTM

[erickzhao]

API LGTM

[clavin]

The API name change came after the formal reviews in this PR; however, the change was supported by API WG members I ran it past (and even in a comment up above), and the ultimate goal is to try deprecating the overlapping clearStorageData in the near future, so I hope that it's okay to keep the existing API reviews for this PR. We have plenty of time to rename in another PR if we ultimately decide to change course.

[release-clerk]

Release Notes Persisted

clearData method added to Session.