From 85d6b1c6fd84b219c2af7a32efd30f5282e8bfa4 Mon Sep 17 00:00:00 2001 From: Oliver Dunk Date: Fri, 28 Jun 2024 15:05:26 +0100 Subject: [PATCH 1/4] Add getKeys() proposal --- proposals/storage-get-keys.md | 115 ++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 proposals/storage-get-keys.md diff --git a/proposals/storage-get-keys.md b/proposals/storage-get-keys.md new file mode 100644 index 00000000..282b6c0f --- /dev/null +++ b/proposals/storage-get-keys.md @@ -0,0 +1,115 @@ +# Proposal: browser.storage.<area>.getKeys + +**Summary** + +API to retrieve all keys for a given storage area in the `browser.storage` API. + +**Document Metadata** + +**Author:** [Oliver Dunk (Google)](https://github.com/oliverdunk) + +**Sponsoring Browser:** Chromium + +**Contributors:** [polywock](https://github.com/polywock) + +**Created:** 2024-06-28 + +**Related Issues:** [#601](https://github.com/w3c/webextensions/issues/601) + +## Motivation + +### Objective + +This API enables developers to retrieve the keys in storage without needing to +receive all of the data stored alongside those keys. Depending on the +implementation, the impact of this optimization may differ - for example +Chromium has only a limited ability to access data from storage without +fetching the associated data. Regardless, this reduces the amount of data +returned to the caller and allows for further optimizations in the future. + +#### Use Cases + +There are existing use cases for enumerating the data in extension storage. For +example, extensions for Chrome that add extension storage areas to DevTools. +While these also need a way to show the associated values, they may not want to +load these upfront. + +Additionally, in some cases developers may want to access keys with a given +prefix, for example if using a key like `foo:tabid`. This API proposal does not +allow matching by prefix (see "Future Work") but developers would be able to do +this themselves after obtaining the list of keys. + +### Known Consumers + +There is developer interest for this API in +[#601](https://github.com/w3c/webextensions/issues/601). While we don't expect +significant immediate usage, it is a small, well-scoped API and should not +represent significant engineering effort. + +## Specification + +### Schema + +```ts +interface StorageArea { + getKeys(): Promise; +} +``` + +The original issue proposed the `getAllKeys()` name, to match IndexedDB. This +proposal suggests the slightly shorter `getKeys()`, since that seems equally +clear and less verbose. + +### Behavior + +This API will throw / populate browser.runtime.lastError in the case of +failure, for example if access to the storage area is not allowed in the +given context. + +### New Permissions + +This API will use the existing `storage` permission. + +### Manifest File Changes + +There are no changes to the manifest. + +## Security and Privacy + +### Exposed Sensitive Data + +This API does not expose any data which is not already accessible to the +extension. + +### Abuse Mitigations + +This does not expose any new data so there are no new abuse vectors. + +### Additional Security Considerations + +N/A + +## Alternatives + +### Existing Workarounds + +Developers can retrieve all data using the `get()` API with `null` as the keys +parameter, which will return everything in storage. This is very similar but +requires all of the data stored for a given key to be returned, which has +performance implications. + +### Open Web API + +In the future, using web storage APIs in WebExtensions would certainly be +desirable. However, the storage API already has significant adoption. +Therefore, there is value in making it more ergonomic for developers. + +## Implementation Notes + +N/A + +## Future Work + +It may be desirable to add a parameter to allow filtering of the keys that are +returned. This is not an optimization we think is neccessary in an initial +implementation. From e6f54b174199a5dfc2a803d27c9087588a3536a6 Mon Sep 17 00:00:00 2001 From: Oliver Dunk Date: Mon, 1 Jul 2024 16:33:35 +0100 Subject: [PATCH 2/4] Update proposals/storage-get-keys.md Co-authored-by: Rob Wu --- proposals/storage-get-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/storage-get-keys.md b/proposals/storage-get-keys.md index 282b6c0f..303dcd1f 100644 --- a/proposals/storage-get-keys.md +++ b/proposals/storage-get-keys.md @@ -62,7 +62,7 @@ clear and less verbose. ### Behavior -This API will throw / populate browser.runtime.lastError in the case of +This API will reject with an Error / populate browser.runtime.lastError in the case of failure, for example if access to the storage area is not allowed in the given context. From f1b92077b5795f41dfa331563134d58daa97dd9d Mon Sep 17 00:00:00 2001 From: Oliver Dunk Date: Mon, 1 Jul 2024 16:34:27 +0100 Subject: [PATCH 3/4] Update proposals/storage-get-keys.md Co-authored-by: Rob Wu --- proposals/storage-get-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/storage-get-keys.md b/proposals/storage-get-keys.md index 303dcd1f..50b5804a 100644 --- a/proposals/storage-get-keys.md +++ b/proposals/storage-get-keys.md @@ -111,5 +111,5 @@ N/A ## Future Work It may be desirable to add a parameter to allow filtering of the keys that are -returned. This is not an optimization we think is neccessary in an initial +returned. This is not an optimization we think is necessary in an initial implementation. From 0c6cea55d74c5d1a0b1b7299af10721540113a85 Mon Sep 17 00:00:00 2001 From: Oliver Dunk Date: Mon, 1 Jul 2024 16:35:12 +0100 Subject: [PATCH 4/4] Update proposals/storage-get-keys.md Co-authored-by: Rob Wu --- proposals/storage-get-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/storage-get-keys.md b/proposals/storage-get-keys.md index 50b5804a..ad54c620 100644 --- a/proposals/storage-get-keys.md +++ b/proposals/storage-get-keys.md @@ -49,7 +49,7 @@ represent significant engineering effort. ## Specification ### Schema - +This proposal expands the existing [StorageArea type](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea) with a new `getKeys` method: ```ts interface StorageArea { getKeys(): Promise;