feat: Add shared dictionary management APIs (#44950)

* Add bare-bones GetSharedDictionaryUsageInfo

* Add GetSharedDictionaryInfo()

* Improve API, use isolation keys

* Add documentation

* Update docs/api/session.md



* Update shell/browser/api/electron_api_session.cc



* Add tests

* Implement feedback <3

* Improve tests

* chore: lint

* docs: add note about clearing cache in ses.clearData

---------

Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Felix Rieseberg <fr@makenotion.com>

docs/api/session.md

@@ -1360,6 +1360,36 @@ specified when registering the protocol.
 
 Returns `Promise<void>` - resolves when the code cache clear operation is complete.
 
+#### `ses.getSharedDictionaryUsageInfo()`
+
+Returns `Promise<SharedDictionaryUsageInfo[]>` - an array of shared dictionary information entries in Chromium's networking service's storage.
+
+Shared dictionaries are used to power advanced compression of data sent over the wire, specifically with Brotli and ZStandard. You don't need to call any of the shared dictionary APIs in Electron to make use of this advanced web feature, but if you do, they allow deeper control and inspection of the shared dictionaries used during decompression.
+
+To get detailed information about a specific shared dictionary entry, call `getSharedDictionaryInfo(options)`.
+
+#### `ses.getSharedDictionaryInfo(options)`
+
+* `options` Object
+  * `frameOrigin` string - The origin of the frame where the request originates. It’s specific to the individual frame making the request and is defined by its scheme, host, and port. In practice, will look like a URL.
+  * `topFrameSite` string - The site of the top-level browsing context (the main frame or tab that contains the request). It’s less granular than `frameOrigin` and focuses on the broader "site" scope. In practice, will look like a URL.
+
+Returns `Promise<SharedDictionaryInfo[]>` - an array of shared dictionary information entries in Chromium's networking service's storage.
+
+To get information about all present shared dictionaries, call `getSharedDictionaryUsageInfo()`.
+
+#### `ses.clearSharedDictionaryCache()`
+
+Returns `Promise<void>` - resolves when the dictionary cache has been cleared, both in memory and on disk.
+
+#### `ses.clearSharedDictionaryCacheForIsolationKey(options)`
+
+* `options` Object
+  * `frameOrigin` string - The origin of the frame where the request originates. It’s specific to the individual frame making the request and is defined by its scheme, host, and port. In practice, will look like a URL.
+  * `topFrameSite` string - The site of the top-level browsing context (the main frame or tab that contains the request). It’s less granular than `frameOrigin` and focuses on the broader "site" scope. In practice, will look like a URL.
+
+Returns `Promise<void>` - resolves when the dictionary cache has been cleared for the specified isolation key, both in memory and on disk.
+
 #### `ses.setSpellCheckerEnabled(enable)`
 
 * `enable` boolean
@@ -1537,6 +1567,8 @@ This method clears more types of data and is more thorough than the
 
 **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](https://url.spec.whatwg.org/#host-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`.
 
+**Note:** Clearing cache data will also clear the shared dictionary cache. This means that any dictionaries used for compression may be reloaded after clearing the cache. If you wish to clear the shared dictionary cache but leave other cached data intact, you may want to use the `clearSharedDictionaryCache` method.
+
 For more information, refer to Chromium's [`BrowsingDataRemover` interface][browsing-data-remover].
 
 ### Instance Properties

docs/api/structures/shared-dictionary-info.md

@@ -0,0 +1,12 @@
+# SharedDictionaryInfo Object
+
+* `match` string - The matching path pattern for the dictionary which was declared in 'use-as-dictionary' response header's `match` option.
+* `matchDestinations` string[] - An array of matching destinations for the dictionary which was declared in 'use-as-dictionary' response header's `match-dest` option.
+* `id` string - The Id for the dictionary which was declared in 'use-as-dictionary' response header's `id` option.
+* `dictionaryUrl` string - URL of the dictionary.
+* `lastFetchTime` Date - The time of when the dictionary was received from the network layer.
+* `responseTime` Date - The time of when the dictionary was received from the server. For cached responses, this time could be "far" in the past.
+* `expirationDuration` number - The expiration time for the dictionary which was declared in 'use-as-dictionary' response header's `expires` option in seconds.
+* `lastUsedTime` Date - The time when the dictionary was last used.
+* `size` number - The amount of bytes stored for this shared dictionary information object in Chromium's internal storage (usually Sqlite).
+* `hash` string - The sha256 hash of the dictionary binary.

docs/api/structures/shared-dictionary-usage-info.md

@@ -0,0 +1,5 @@
+# SharedDictionaryUsageInfo Object
+
+* `frameOrigin` string - The origin of the frame where the request originates. It’s specific to the individual frame making the request and is defined by its scheme, host, and port. In practice, will look like a URL.
+* `topFrameSite` string - The site of the top-level browsing context (the main frame or tab that contains the request). It’s less granular than `frameOrigin` and focuses on the broader "site" scope. In practice, will look like a URL.
+* `totalSizeBytes` number - The amount of bytes stored for this shared dictionary information object in Chromium's internal storage (usually Sqlite).