From f696843c13d23f147081c2e87f0c2e52aadde533 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Fri, 5 Jun 2020 20:16:42 +0200 Subject: [PATCH] Add hooks for HTML "legacy-clone a browsing session storage shed" can be used by HTML to define creation of auxiliary browsing contexts, as part of https://github.com/whatwg/html/pull/5560. "obtain a storage key" can be used by APIs that share keying logic with storage, such as BroadcastChannel and shared workers. See https://github.com/whatwg/html/issues/3054. It's potentially also useful for Indexed DB as discussed in https://github.com/w3c/IndexedDB/pull/334. Also helps a bit with #95 by reorganizing and adding some more detail to how a user agent is supposed to manage storage. Closes #92. --- storage.bs | 151 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 103 insertions(+), 48 deletions(-) diff --git a/storage.bs b/storage.bs index 3d42d31..a86856e 100644 --- a/storage.bs +++ b/storage.bs @@ -84,8 +84,8 @@ function retrieveNextChunk(nextChunkInfo) {

This specification depends on the Infra Standard. [[!INFRA]] -

This specification uses terminology from the DOM, HTML, IDL, Permissions API, and URL Standards. -[[DOM]] [[HTML]] [[WEBIDL]] [[PERMISSIONS]] [[URL]] +

This specification uses terminology from the HTML, IDL, and Permissions Standards. +[[!HTML]] [[!WEBIDL]] [[!PERMISSIONS]] @@ -195,13 +195,30 @@ anticipated that some APIs will be applicable to both storage types going -

Storage sheds

+

Storage keys

-

A storage key is an origin. [[HTML]] +

A storage key is an origin. [[!HTML]] -

This is expected to change, see +

This is expected to change; see Client-Side Storage Partitioning. +

To obtain a storage key, given an environment settings object +environment, run these steps: + +

    +

  1. Let key be environment's + origin. + +

  2. If key is an opaque origin, then return failure. + +

  3. If the user has disabled storage, then return failure. + +

  4. Return key. +

+ + +

Storage sheds

+

A storage shed is a map of storage keys to storage shelves. It is initially empty. @@ -211,15 +228,36 @@ It is initially empty. storage shed. A user agent's storage shed holds all local storage data. -

A browsing session holds a storage shed, which is a -storage shed. A browsing session's storage shed holds all -session storage data. +

A browsing session holds a storage shed, which is +a storage shed. A browsing session's +storage shed holds all session storage data. + +

To legacy-clone a browsing session storage shed, given a +browsing session A and a browsing session B, run +these steps: + +

    +
  1. +

    For each key → shelf of A's + storage shed: + +

      +

    1. Let newShelf be the result of running create a storage shelf with + "session". + +

    2. Set newShelf's bucket map["default"]'s + bottle map["sessionStorage"]'s map to a + clone of shelf's bucket map["default"]'s + bottle map["sessionStorage"]'s map. + +

    3. Set B's storage shed[key] to + newShelf. +

    +
-

See -whatwg/html issue #4782 and -whatwg/html issue #5350 for defining -browsing session. It is roughly analogous to top-level browsing context except that it cannot -be replaced due to Cross-Origin-Opener-Policy or navigation. +

This is considered legacy as the benefits, if any, do not outweigh the +implementation complexity. And therefore it will not be expanded or used outside of +HTML. [[HTML]]

Storage shelves

@@ -238,24 +276,14 @@ given a value when a storage shelf is type, run these steps:
    -

  1. Let key be environment's - origin. - -

  2. If key is an opaque origin, then return failure. - -

  3. If the user has disabled storage, then return failure. - -

  4. -

    If shed[key] does not exist, then: - -

      -

    1. Let shelf be a new storage shelf. +

    2. Let key be the result of running obtain a storage key with + environment. -

    3. Set shelf's bucket map["default"] to the result of - create a storage bucket with type. +

    4. If key is failure, then return failure. -

    5. Set shed[key] to shelf. -

    +

  5. If shed[key] does not exist, then set + shed[key] to the result of running create a storage shelf with + type.

  6. Return shed[key].

@@ -264,12 +292,22 @@ given a value when a storage shelf is environment, return the result of running obtain a storage shelf with the user agent's storage shed, environment, and "local". +

To create a storage shelf, given a storage type type, run these +steps: + +

    +

  1. Let shelf be a new storage shelf. + +

  2. Set shelf's bucket map["default"] to the result of running + create a storage bucket with type. + +

  3. Return shelf. +

+

Storage buckets

-

A storage bucket is a place for storage endpoints to store data. Whenever a -storage bucket is cleared by the user agent, it must be cleared in its entirety. - +

A storage bucket is a place for storage endpoints to store data.

A storage bucket has a bottle map of storage identifiers to storage bottles. @@ -352,7 +390,7 @@ standard and standards using this standard can access the contents.

  • Assert: type is "session".

  • Set shed to environment's - browsing session's + browsing session's storage shed. @@ -450,28 +488,45 @@ evaluating quotas. -

    User Interface Guidelines

    +

    Management

    + +

    Whenever a storage bucket is cleared by the user agent, it must be cleared in its +entirety. User agents should avoid clearing storage buckets while script that is able to +access them is running, unless instructed otherwise by the user. + +

    If removal of storage buckets leaves the encompassing storage shelf's +bucket map empty, then remove that +storage shelf and corresponding storage key from the encompassing +storage shed. + + +

    Storage pressure

    + +

    A user agent that comes under storage pressure should clear network state and +local storage buckets whose mode is +"best-effort", ideally prioritizing removal in a manner that least impacts the user. + +

    If a user agent continues to be under storage pressure, then the user agent should inform the +user and offer a way to clear the remaining local storage buckets, i.e., those whose +mode is "persistent". + +

    Session storage buckets must be cleared as browsing sessions are closed. + +

    If the user agent allows for revival of browsing sessions, e.g., +through reopening browsing sessions or continued use of them after restarting the user +agent, then clearing necessarily involves a more complex set of heuristics. + + +

    User interface guidelines

    User agents should not distinguish between network state and storage in their user interface. -Instead user agents should offer users the ability to remove all storage for each group of +Instead user agents should offer users the ability to clear all storage for each group of schemelessly same site origins. This ensures to some extent that network state cannot be used to revive storage. This also reduces the amount users need to know about the different ways in which websites can store data. -

    Credentials should be separated as they contain data the user might not be able to revive, such as an autogenerated password. Permissions are best separated too to avoid inconveniencing the user. -Credentials and permissions are also somewhat easier to understand and differentiate for users from -network state and storage. - - -

    Storage Pressure

    - -

    When the user agent notices it comes under storage pressure and it cannot free up sufficient -space by clearing network state, session storage buckets, and local storage buckets -whose mode is "best-effort", then the user agent -should inform the user and offer a way to clear the remaining local storage buckets, i.e., -those whose mode is "persistent". @@ -486,7 +541,7 @@ Navigator includes NavigatorStorage; WorkerNavigator includes NavigatorStorage; -

    Each environment settings object has an associated {{StorageManager}} object. [[HTML]] +

    Each environment settings object has an associated {{StorageManager}} object. [[!HTML]]

    The storage getter steps are to return this's relevant settings object's {{StorageManager}} object.